agents-relay 2.0.208 → 2.0.209
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/dist/adapters.js +2 -1
- package/dist/agent-shortcut.js +113 -41
- package/dist/browser-worker-runtime.js +7 -2
- package/dist/chatgpt-platform-fallback.js +30 -0
- package/dist/cli-shortcut-local.js +49 -0
- package/dist/cli-shortcut.js +81 -19
- package/dist/cli.js +8 -3
- package/dist/force-restate-validation.js +3 -1
- package/dist/job-execution-slot.js +4 -1
- package/dist/model-routing.js +8 -0
- package/dist/reconciler-review.js +32 -13
- package/dist/reconciler-runtime.js +43 -54
- package/dist/reconciler.js +12 -2
- package/dist/relay-job-snapshot-reads.js +5 -2
- package/dist/relay-workflow-operations.js +1 -1
- package/dist/runtime-status.js +11 -4
- package/dist/shortcut-node-worker.js +128 -0
- package/dist/shortcut-stage-contract.js +50 -0
- package/dist/shortcut-worker-runner.js +73 -0
- package/dist/task-actions.js +4 -13
- package/dist/task-inactivity-watchdog.js +7 -0
- package/dist/terminal-event-recovery.js +13 -0
- package/dist/worker-failure-recovery.js +89 -0
- package/dist/workflow/contracts.js +4 -0
- package/dist/workflow/definitions-v2.js +2 -0
- package/dist/workflow/runtime.js +30 -0
- package/dist/workflow/task-resolution.js +1 -4
- package/package.json +4 -3
- package/skills/agents-relay/agents/planner.agent.md +14 -4
- package/skills/agents-relay/agents/reviewer.agent.md +2 -0
- package/skills/agents-relay/contracts/orchestrator-workflows.md +6 -0
- package/skills/agents-relay/contracts/task-job-contract.md +4 -0
- package/workflow/force-restate-validation.mmd +1 -1
- package/workflow/review-lifecycle.mmd +1 -1
- package/workflow/task-lifecycle.mmd +13 -12
- package/workflow/task-resolution.mmd +1 -6
package/dist/task-actions.js
CHANGED
|
@@ -47,11 +47,6 @@ function clearExecution(task) {
|
|
|
47
47
|
task.leaseExpiresAt = null;
|
|
48
48
|
task.executionId = null;
|
|
49
49
|
}
|
|
50
|
-
function markShortcutWorkerFallback(task) {
|
|
51
|
-
const data = task.result?.data ?? {};
|
|
52
|
-
const shortcut = data.shortcut && typeof data.shortcut === 'object' ? data.shortcut : {};
|
|
53
|
-
task.result = { summary: task.result?.summary ?? 'Troubleshooter selected original Worker recovery', data: { ...data, shortcut: { ...shortcut, workerFallback: true } } };
|
|
54
|
-
}
|
|
55
50
|
function applyTaskRetrySnapshot(task, policy = {}) {
|
|
56
51
|
if (task.kind === 'planner')
|
|
57
52
|
throw new Error(`Legacy planner Task ${task.id} is read-only; retry the Plan instead`);
|
|
@@ -227,11 +222,9 @@ export async function dispatchTaskAction(store, request) {
|
|
|
227
222
|
if (!recovery.executionId)
|
|
228
223
|
throw new Error(`Troubleshooter ${recovery.id} has no current execution for a fresh resolution`);
|
|
229
224
|
const proposal = { path: 'exact_original_retry', targetTaskId: task.id, recoveryExecutionId: recovery.executionId, rootCause: task.failureReason ?? task.error ?? 'durable failure', solution: `Recover exact original Task via ${request.recoveryTaskId}` };
|
|
230
|
-
const activateRecovery = (
|
|
231
|
-
markShortcutWorkerFallback(task); recordRecoveryRouting(task, request); task.resolution = { ...materializeResolution(task, proposal, 'troubleshooter'), state: 'resolved' }; };
|
|
225
|
+
const activateRecovery = () => { applyTaskRetrySnapshot(task, { extendBudget: true }); recordRecoveryRouting(task, request); task.resolution = { ...materializeResolution(task, proposal, 'troubleshooter'), state: 'resolved' }; };
|
|
232
226
|
const decision = dispatchTaskResolutionSync(task, proposal, 'troubleshooter', {
|
|
233
|
-
activateRecovery
|
|
234
|
-
activateShortcutWorkerFallback: () => activateRecovery(true),
|
|
227
|
+
activateRecovery,
|
|
235
228
|
});
|
|
236
229
|
if (!decision.accepted)
|
|
237
230
|
throw new Error(`Task resolution graph rejected exact-original recovery for ${task.id}`);
|
|
@@ -268,11 +261,9 @@ export async function dispatchTaskAction(store, request) {
|
|
|
268
261
|
if (!recovery.executionId)
|
|
269
262
|
throw new Error(`Troubleshooter ${recovery.id} has no current execution for a fresh resolution`);
|
|
270
263
|
const proposal = { path: 'exact_original_retry', targetTaskId: task.id, recoveryExecutionId: recovery.executionId, rootCause: task.failureReason ?? task.error ?? 'durable failure', solution: `Recover exact original Task via ${request.recoveryTaskId}` };
|
|
271
|
-
const activateRecovery = (
|
|
272
|
-
markShortcutWorkerFallback(task); recordRecoveryRouting(task, request); task.resolution = { ...materializeResolution(task, proposal, 'troubleshooter'), state: 'resolved' }; };
|
|
264
|
+
const activateRecovery = () => { applyTaskRetrySnapshot(task, { extendBudget: true }); recordRecoveryRouting(task, request); task.resolution = { ...materializeResolution(task, proposal, 'troubleshooter'), state: 'resolved' }; };
|
|
273
265
|
const decision = dispatchTaskResolutionSync(task, proposal, 'troubleshooter', {
|
|
274
|
-
activateRecovery
|
|
275
|
-
activateShortcutWorkerFallback: () => activateRecovery(true),
|
|
266
|
+
activateRecovery,
|
|
276
267
|
});
|
|
277
268
|
if (!decision.accepted)
|
|
278
269
|
throw new Error(`Task resolution graph rejected exact-original recovery for ${task.id}`);
|
|
@@ -1,4 +1,11 @@
|
|
|
1
1
|
import { executionEventSource, eventSourceId } from './execution-event-identity.js';
|
|
2
|
+
/** A foreground Shortcut Graph parent is not a Worker: its elapsed budget
|
|
3
|
+
* belongs to the direct runner. Real Worker child Tasks keep standard timeouts. */
|
|
4
|
+
export function requiresWorkerInactivityWatchdog(job, task) {
|
|
5
|
+
const shortcut = task.result?.data?.shortcut;
|
|
6
|
+
return !(job.executionMode === 'shortcut' && job.contentOnly === true
|
|
7
|
+
&& Boolean(task.agentGraph) && shortcut?.workerFallback !== true);
|
|
8
|
+
}
|
|
2
9
|
export function isRecoverableWatchdogFailure(task) {
|
|
3
10
|
if (['worker_start_timeout', 'terminal_event_timeout', 'worker_exit_before_start', 'worker_exit_without_terminal_event', 'worker_delivery_after_start'].includes(task.failureReason ?? ''))
|
|
4
11
|
return true;
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/** Shared, adapter-neutral terminal-event recovery policy.
|
|
2
|
+
* A recovery turn is not a Task retry, progress event, or completion proof.
|
|
3
|
+
* Only an existing resumable conversation for the ORIGINAL execution qualifies.
|
|
4
|
+
*/
|
|
5
|
+
export const MAX_TERMINAL_RECOVERY_TURNS = 1;
|
|
6
|
+
export function terminalRecoveryEligible(facts) {
|
|
7
|
+
return facts.hasSession && facts.hasThread && !facts.terminalObserved
|
|
8
|
+
&& !facts.outcomeUncertain && !facts.cancelled
|
|
9
|
+
&& facts.recoveryAttempts < MAX_TERMINAL_RECOVERY_TURNS;
|
|
10
|
+
}
|
|
11
|
+
export function terminalRecoveryPrompt(executionId) {
|
|
12
|
+
return `[Relay terminal-event recovery: ${executionId}]\nThis is ONE reminder for the ORIGINAL Task execution, not a new task or authorization to restart work. Inspect the authoritative Task context, Neo event history, and actual output. If a correlated terminal event already exists, do not publish a duplicate. If work is complete with verified evidence, publish task.completed with the ORIGINAL execution identity. If unfinished or unverified, publish task.failed with the real reason; do not claim success. Follow the canonical event contract. Do not emit task.progress merely because this reminder arrived.`;
|
|
13
|
+
}
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import { hasSafeAlternativeWorker } from './browser-worker-routing.js';
|
|
2
|
+
import { codexNoStartFallbackRoute, persistChatGptPlatformFailure } from './chatgpt-platform-fallback.js';
|
|
3
|
+
import { classifyChatGptPlatformFailure } from './worker-rejection.js';
|
|
4
|
+
import { recordLaunchRouteOutcome } from './route-outcome-recording.js';
|
|
5
|
+
import { eventFor } from './events.js';
|
|
6
|
+
export async function handleWorkerLaunchFailure(ports, jobId, taskId, executionId, failure, phase = 'launch') {
|
|
7
|
+
const message = failure instanceof Error ? failure.message : String(failure);
|
|
8
|
+
const currentJob = await ports.store.load(jobId);
|
|
9
|
+
const currentTask = currentJob.tasks.find(task => task.id === taskId);
|
|
10
|
+
const agents = await ports.store.listAgents();
|
|
11
|
+
const usage = ports.usageSnapshotProvider ? await ports.usageSnapshotProvider() : undefined;
|
|
12
|
+
const alternative = hasSafeAlternativeWorker(currentTask, ports.adapters, agents, usage);
|
|
13
|
+
const activeExecution = ports.live(taskId);
|
|
14
|
+
const noStarted = currentTask?.state === 'QUEUED'
|
|
15
|
+
&& currentTask.executionId === executionId
|
|
16
|
+
&& !currentTask.lastProgressEventAt
|
|
17
|
+
&& !activeExecution?.workerStarted;
|
|
18
|
+
const canRetryNoStart = noStarted && currentJob.executionMode !== 'shortcut'
|
|
19
|
+
&& (currentTask?.adapter === 'chatgpt' || currentTask?.adapter === 'z')
|
|
20
|
+
&& currentTask.agentName !== 'reviewer'
|
|
21
|
+
&& currentTask.agentName !== 'troubleshooter' && currentTask.kind !== 'planner'
|
|
22
|
+
&& !currentTask.noStartFallback && currentTask.attempt < currentTask.maxAttempts;
|
|
23
|
+
const codexFallback = canRetryNoStart
|
|
24
|
+
? await codexNoStartFallbackRoute(currentTask, ports.adapters, agents, usage)
|
|
25
|
+
: null;
|
|
26
|
+
const noStartFallbackAllowed = Boolean(canRetryNoStart && codexFallback);
|
|
27
|
+
const platformFailure = (currentTask?.adapter === 'chatgpt' || currentTask?.adapter === 'z')
|
|
28
|
+
? classifyChatGptPlatformFailure(failure, phase === 'process' || phase === 'terminal' ? 'delivery' : phase)
|
|
29
|
+
: undefined;
|
|
30
|
+
const unknownOutcome = phase === 'start-ack' || ['outcome_unknown', 'start_ack_timeout'].includes(platformFailure?.classification ?? '')
|
|
31
|
+
|| (phase === 'launch' && activeExecution?.executionId === executionId)
|
|
32
|
+
|| (phase === 'delivery' && activeExecution?.executionId === executionId && activeExecution.workerStarted);
|
|
33
|
+
const failureReason = phase === 'start-ack' ? 'worker_start_timeout'
|
|
34
|
+
: /WEBHELM_UNAVAILABLE|webhelm runtime dependency unavailable|webhelm session start returned no session_id|no close frame received or sent/i.test(message)
|
|
35
|
+
? 'browser_workspace_unavailable'
|
|
36
|
+
: undefined;
|
|
37
|
+
const claim = executionId ?? `${jobId}:${taskId}`;
|
|
38
|
+
if (ports.launchFailureClaims.has(claim))
|
|
39
|
+
return;
|
|
40
|
+
ports.launchFailureClaims.add(claim);
|
|
41
|
+
const cleanup = setTimeout(() => ports.launchFailureClaims.delete(claim), 60000);
|
|
42
|
+
cleanup.unref();
|
|
43
|
+
const workflowEvent = noStartFallbackAllowed ? 'worker.no_start_failed'
|
|
44
|
+
: platformFailure ? 'worker.platform_failure'
|
|
45
|
+
: phase === 'start-ack' ? 'worker.start_ack_failed' : 'worker.delivery_failed';
|
|
46
|
+
const transition = await ports.taskTransitions.apply(jobId, taskId, workflowEvent, {
|
|
47
|
+
eligible: (_job, task) => task.executionId === executionId,
|
|
48
|
+
facts: () => ({
|
|
49
|
+
platformFallbackSafe: platformFailure?.safeToReroute === true && alternative,
|
|
50
|
+
noStartFallbackAllowed: noStartFallbackAllowed && !currentTask?.noStartFallback,
|
|
51
|
+
}),
|
|
52
|
+
mutate: (_job, task, decision) => {
|
|
53
|
+
if (platformFailure && workflowEvent !== 'worker.no_start_failed')
|
|
54
|
+
persistChatGptPlatformFailure(task, currentTask, executionId, platformFailure.classification, platformFailure.evidence, platformFailure.safeToReroute);
|
|
55
|
+
if (workflowEvent === 'worker.no_start_failed' && task.noStartFallback)
|
|
56
|
+
task.noStartFallback.reason = message;
|
|
57
|
+
task.error = decision.target === 'QUEUED' ? null : `Worker ${phase} failed: ${message}`;
|
|
58
|
+
task.failureReason = decision.target === 'QUEUED' ? undefined : unknownOutcome
|
|
59
|
+
? 'worker_outcome_unknown' : platformFailure ? 'worker_platform_failure' : failureReason;
|
|
60
|
+
task.leaseOwner = null;
|
|
61
|
+
task.leaseExpiresAt = null;
|
|
62
|
+
task.executionId = null;
|
|
63
|
+
},
|
|
64
|
+
});
|
|
65
|
+
if (!transition)
|
|
66
|
+
return;
|
|
67
|
+
if (!transition.decision.accepted) {
|
|
68
|
+
await ports.emit(eventFor(jobId, taskId, transition.task.parentTaskId, 'task.process.delivery_failed', 'failed', `Worker ${phase} reported after lifecycle moved to ${transition.from}: ${message}`, 'orchestrator', { phase, authoritative: false, executionId, workflowEvent }, { agent: 'relay', component: 'agents-relay' }));
|
|
69
|
+
return;
|
|
70
|
+
}
|
|
71
|
+
await recordLaunchRouteOutcome(ports.decisionAuditStore, currentTask ?? transition.task, message, phase === 'process' || phase === 'terminal' ? 'delivery' : phase, executionId, unknownOutcome);
|
|
72
|
+
if (executionId) {
|
|
73
|
+
const live = ports.live(taskId);
|
|
74
|
+
if (live?.executionId === executionId) {
|
|
75
|
+
live.controller.abort();
|
|
76
|
+
live.execution.cancel();
|
|
77
|
+
ports.clearExecution(taskId, executionId);
|
|
78
|
+
}
|
|
79
|
+
// Browser after-terminal waits must not outlive this failed generation:
|
|
80
|
+
// otherwise they could reject a legitimate terminal event from Codex.
|
|
81
|
+
ports.clearTerminalWaiter(taskId, executionId);
|
|
82
|
+
}
|
|
83
|
+
const event = eventFor(jobId, taskId, transition.task.parentTaskId, transition.task.state === 'QUEUED' && workflowEvent === 'worker.no_start_failed'
|
|
84
|
+
? 'worker.no_start_fallback' : transition.task.state === 'QUEUED' ? 'worker.pre_submission_rejected' : 'task.failed', transition.task.state === 'QUEUED' ? 'queued' : 'failed', transition.task.error ?? `Worker ${phase} failed: ${message}`, 'user', { phase, reason: transition.task.failureReason ?? failureReason, workflowEvent,
|
|
85
|
+
...(transition.task.noStartFallback ? { noStartFallback: transition.task.noStartFallback } : {}),
|
|
86
|
+
...(transition.task.platformFailure ? { platformFailure: transition.task.platformFailure } : {}) }, { agent: 'relay', component: 'agents-relay', watchdog: true });
|
|
87
|
+
ports.detach(ports.emit(event), jobId, taskId, 'worker failure event');
|
|
88
|
+
ports.wake(jobId, taskId, `worker-${phase}-failure`);
|
|
89
|
+
}
|
|
@@ -50,6 +50,7 @@ export const WORKFLOW_EVENT_NAMES = [
|
|
|
50
50
|
'worker.delivery_failed',
|
|
51
51
|
'worker.start_ack_failed',
|
|
52
52
|
'worker.platform_failure',
|
|
53
|
+
'worker.no_start_failed',
|
|
53
54
|
];
|
|
54
55
|
export const WORKFLOW_FACT_NAMES = [
|
|
55
56
|
'dependenciesSatisfied',
|
|
@@ -59,6 +60,7 @@ export const WORKFLOW_FACT_NAMES = [
|
|
|
59
60
|
'shortcutExecution',
|
|
60
61
|
'shortcutFallback',
|
|
61
62
|
'shortcutHasGraph',
|
|
63
|
+
'shortcutDirectInvocation',
|
|
62
64
|
'shortcutEffectsSafe',
|
|
63
65
|
'shortcutResultCorrelated',
|
|
64
66
|
'notMerged',
|
|
@@ -74,6 +76,7 @@ export const WORKFLOW_FACT_NAMES = [
|
|
|
74
76
|
'headAvailable',
|
|
75
77
|
'mergeCapable',
|
|
76
78
|
'platformFallbackSafe',
|
|
79
|
+
'noStartFallbackAllowed',
|
|
77
80
|
];
|
|
78
81
|
export const WORKFLOW_MUTATION_NAMES = [
|
|
79
82
|
'mutation.clearError',
|
|
@@ -87,6 +90,7 @@ export const WORKFLOW_MUTATION_NAMES = [
|
|
|
87
90
|
'mutation.markShortcutWorkerFallback',
|
|
88
91
|
'mutation.markShortcutRecoveryRequired',
|
|
89
92
|
'mutation.preparePlatformFallback',
|
|
93
|
+
'mutation.prepareNoStartFallback',
|
|
90
94
|
'mutation.quarantinePlatformFailure',
|
|
91
95
|
];
|
|
92
96
|
export const WORKFLOW_EFFECT_NAMES = [
|
|
@@ -32,6 +32,7 @@ export const taskLifecycleV2 = load('task-lifecycle', TASK_STATES, {
|
|
|
32
32
|
shortcutExecution: facts => facts.durableFacts.shortcutExecution === true,
|
|
33
33
|
shortcutFallback: facts => facts.durableFacts.shortcutFallback === true,
|
|
34
34
|
shortcutHasGraph: facts => facts.durableFacts.shortcutHasGraph === true,
|
|
35
|
+
shortcutDirectInvocation: facts => facts.durableFacts.shortcutDirectInvocation === true,
|
|
35
36
|
shortcutEffectsSafe: facts => facts.durableFacts.shortcutEffectsSafe === true,
|
|
36
37
|
shortcutResultCorrelated: facts => facts.durableFacts.shortcutResultCorrelated === true,
|
|
37
38
|
recoverableExecution: boolGuard('recoverableExecution'),
|
|
@@ -40,6 +41,7 @@ export const taskLifecycleV2 = load('task-lifecycle', TASK_STATES, {
|
|
|
40
41
|
awaitingInteractiveDecision: facts => facts.durableFacts.awaitingInteractiveDecision === true,
|
|
41
42
|
retryAvailable: boolGuard('retryAvailable'),
|
|
42
43
|
platformFallbackSafe: facts => facts.durableFacts.platformFallbackSafe === true,
|
|
44
|
+
noStartFallbackAllowed: facts => facts.durableFacts.noStartFallbackAllowed === true,
|
|
43
45
|
});
|
|
44
46
|
export const jobLifecycleV2 = load('job-lifecycle', JOB_STATES, {
|
|
45
47
|
notMerged: boolGuard('notMerged'),
|
package/dist/workflow/runtime.js
CHANGED
|
@@ -47,6 +47,36 @@ export function applyTaskMutation(task, mutation) {
|
|
|
47
47
|
if (mutation === 'mutation.markShortcutRecoveryRequired') {
|
|
48
48
|
task.failureReason = 'shortcut_requires_recovery';
|
|
49
49
|
}
|
|
50
|
+
if (mutation === 'mutation.prepareNoStartFallback') {
|
|
51
|
+
const route = task.routing;
|
|
52
|
+
if (task.adapter !== 'chatgpt' && task.adapter !== 'z')
|
|
53
|
+
throw new Error('No-start fallback is only legal for ChatGPT/Z Workers');
|
|
54
|
+
const originalAdapter = task.adapter;
|
|
55
|
+
const workerId = task.workerSelection?.workerId ?? originalAdapter;
|
|
56
|
+
const failedAt = new Date().toISOString();
|
|
57
|
+
task.noStartFallback = {
|
|
58
|
+
failedExecutionId: task.executionId ?? 'missing',
|
|
59
|
+
failedAttempt: task.attempt,
|
|
60
|
+
previous: { adapter: originalAdapter, workerId,
|
|
61
|
+
provider: route?.provider ?? 'unknown', model: route?.model ?? 'unknown',
|
|
62
|
+
...(route?.profile ? { profile: route.profile } : {}) },
|
|
63
|
+
reason: task.error ?? 'Worker failed without an accepted task.started event',
|
|
64
|
+
at: failedAt,
|
|
65
|
+
};
|
|
66
|
+
task.routingExclusions = [...(task.routingExclusions ?? []), {
|
|
67
|
+
adapter: originalAdapter, workerId, provider: route?.provider ?? 'unknown',
|
|
68
|
+
model: route?.model ?? 'unknown',
|
|
69
|
+
...(route?.profile ? { profile: route.profile } : {}),
|
|
70
|
+
reason: 'no_started_event', at: failedAt,
|
|
71
|
+
}];
|
|
72
|
+
task.error = null;
|
|
73
|
+
task.failureReason = undefined;
|
|
74
|
+
task.routing = undefined;
|
|
75
|
+
task.workerSelection = undefined;
|
|
76
|
+
task.leaseOwner = null;
|
|
77
|
+
task.leaseExpiresAt = null;
|
|
78
|
+
task.executionId = null;
|
|
79
|
+
}
|
|
50
80
|
if (mutation === 'mutation.preparePlatformFallback') {
|
|
51
81
|
task.error = null;
|
|
52
82
|
task.failureReason = undefined;
|
|
@@ -11,7 +11,6 @@ export const taskResolutionV2 = new GraphRuntime(source, {
|
|
|
11
11
|
guards: {
|
|
12
12
|
recoveryOwnerAvailable: boolGuard('recoveryOwnerAvailable'), plannerOwnerAvailable: boolGuard('plannerOwnerAvailable'),
|
|
13
13
|
exactOriginalRetry: boolGuard('exactOriginalRetry'), sameJobDependency: boolGuard('sameJobDependency'),
|
|
14
|
-
shortcutInterrupted: boolGuard('shortcutInterrupted'),
|
|
15
14
|
blockerJobDependency: boolGuard('blockerJobDependency'), escalationGate: boolGuard('escalationGate'), genuinelyObsolete: boolGuard('genuinelyObsolete'),
|
|
16
15
|
freshRecoveryExecution: boolGuard('freshRecoveryExecution'),
|
|
17
16
|
classifiableFailure: boolGuard('classifiableFailure'),
|
|
@@ -65,9 +64,7 @@ export function validateResolutionProposal(job, original, proposal) {
|
|
|
65
64
|
export function resolutionFacts(task, proposal, owner) {
|
|
66
65
|
const freshRecoveryExecution = owner !== 'troubleshooter' || proposal.path !== 'exact_original_retry' || (Boolean(proposal.recoveryExecutionId)
|
|
67
66
|
&& proposal.recoveryExecutionId !== task.resolution?.recoveryExecutionId);
|
|
68
|
-
|
|
69
|
-
const shortcutInterrupted = owner === 'troubleshooter' && Boolean(shortcut && typeof shortcut === 'object' && Object.keys(shortcut.inFlight ?? {}).length > 0);
|
|
70
|
-
return { recoveryOwnerAvailable: owner === 'troubleshooter', plannerOwnerAvailable: owner !== null && owner !== 'troubleshooter', exactOriginalRetry: proposal.path === 'exact_original_retry' && task.state === 'FAILED', shortcutInterrupted, sameJobDependency: proposal.path === 'same_job_dependency' && owner !== null && proposal.targetTaskId !== task.id, blockerJobDependency: proposal.path === 'blocker_job_dependency' && owner !== null && Boolean(proposal.targetJobId && proposal.mode), escalationGate: proposal.path === 'escalation_gate' && owner === 'troubleshooter' && Boolean(proposal.rootCause && proposal.solution), genuinelyObsolete: proposal.path === 'cancel_supersede' && Boolean(proposal.rootCause), freshRecoveryExecution, unresolved: unresolvedTask(task) };
|
|
67
|
+
return { recoveryOwnerAvailable: owner === 'troubleshooter', plannerOwnerAvailable: owner !== null && owner !== 'troubleshooter', exactOriginalRetry: proposal.path === 'exact_original_retry' && task.state === 'FAILED', sameJobDependency: proposal.path === 'same_job_dependency' && owner !== null && proposal.targetTaskId !== task.id, blockerJobDependency: proposal.path === 'blocker_job_dependency' && owner !== null && Boolean(proposal.targetJobId && proposal.mode), escalationGate: proposal.path === 'escalation_gate' && owner === 'troubleshooter' && Boolean(proposal.rootCause && proposal.solution), genuinelyObsolete: proposal.path === 'cancel_supersede' && Boolean(proposal.rootCause), freshRecoveryExecution, unresolved: unresolvedTask(task) };
|
|
71
68
|
}
|
|
72
69
|
export function decideTaskResolution(task, proposal, owner) {
|
|
73
70
|
return checkedResolutionDecision(dispatchWorkflowGraphSync(taskResolutionV2, { initialState: 'unresolved', input: { transport: 'event', id: 'resolution.propose', payload: proposal }, durableFacts: resolutionFacts(task, proposal, owner), graphName: 'task-resolution', isTransientState: state => ['check_owner', 'check_path', 'check_fresh_execution'].includes(state), maxSteps: 8 }));
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agents-relay",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.209",
|
|
4
4
|
"description": "Durable async agent jobs coordinated through GitHub pull requests",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -17,8 +17,9 @@
|
|
|
17
17
|
"test:chatgpt-temp-quality": "AGENTS_RELAY_RUN_CHATGPT_TEMP_QUALITY=1 sh -c \"npm run build && node test/quality/run-temporary-chat.mjs\"",
|
|
18
18
|
"dev": "tsx src/cli.ts",
|
|
19
19
|
"test:publish": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 --test-force-exit test/*.test.js",
|
|
20
|
-
"test:
|
|
21
|
-
"test:
|
|
20
|
+
"test:shortcut:dags": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 test/verification/shortcut-dag-matrix.test.mjs test/agent-shortcut.test.js",
|
|
21
|
+
"test:fast": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=2 test/workflow-lifecycle.test.js test/workflow-v2-lifecycle-parity.test.js test/workflow-effects.test.js test/relay-store.test.js test/local-authority.test.js test/local-jobid-routing.test.js test/local-sqlite-jobid.test.js test/no-github.test.js test/reconcile-coordinator.test.js test/service-publication.test.js test/github-webhook.test.js test/verification/shortcut-dag-matrix.test.mjs",
|
|
22
|
+
"test:full": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 test/*.test.js test/verification/shortcut-dag-matrix.test.mjs && npm run test:verification:l3",
|
|
22
23
|
"test:verification:l1": "npm run build && node --test test/verification/harness.test.mjs test/verification/contract.test.mjs test/browser-worker-pool-graph.test.js test/verification/graph-inventory.test.mjs test/verification/dashboard-drilldown.test.mjs test/verification/evidence-matrix.test.mjs test/verification/task-resolution-classification.test.mjs test/verification/planner-contract.test.mjs test/verification/force-restate-validation.test.mjs test/planner-child-recovery.test.js",
|
|
23
24
|
"test:verification:l4:contracts": "npm run build && node --test test/verification/l4/prompt-evals.test.mjs",
|
|
24
25
|
"test:verification:l4": "node test/verification/l4/run-all.mjs",
|
|
@@ -32,10 +32,10 @@ For every non-satisfied objective:
|
|
|
32
32
|
|
|
33
33
|
### Objective decomposition and convergence
|
|
34
34
|
|
|
35
|
-
-
|
|
36
|
-
-
|
|
35
|
+
- Group implementation, deterministic tests, and self-review under the responsible Agent Task when they share one owner. Create a separate durable Task only for a genuinely independent owner, externally meaningful approval boundary, or separately recoverable outcome; do not split checks by technical layer or require a live-service test before that service can be published.
|
|
36
|
+
- Keep technical phases and review-fix iterations within one Agent Task whenever they share responsibility, including a large multi-area implementation. Split only when different Agent roles own independent durable outcomes or a real approval/ownership boundary requires it; preserve genuine dependencies.
|
|
37
37
|
- For a failed Task with repeated deterministic acceptance gaps, do not reissue the identical broad assignment. Identify the *missing acceptance cases*, create focused same-Job repair Tasks with valid `same_job_dependency` resolutions, and specify how their evidence unblocks the original Task. Preserve the original failed Task and failure history.
|
|
38
|
-
- For event-driven workflows,
|
|
38
|
+
- For event-driven workflows, require deterministic ingress/persistence, negative-path, restart and no-false-completion evidence before publishing. Do not elevate tests that require the newly published live runtime/provider/device to release-blocking Tasks merely because they are independently observable.
|
|
39
39
|
- In `assessment`, show the entire remaining objective as a dependency graph, clearly distinguishing already proven work, the executable batch, subsequent verification, and Relay-owned review/merge. Never report overall `satisfied` merely because one batch has passed.
|
|
40
40
|
|
|
41
41
|
|
|
@@ -52,6 +52,16 @@ If an intermediate result does not need that independent lifecycle, keep it insi
|
|
|
52
52
|
|
|
53
53
|
Keep sibling Tasks at a comparable abstraction level. Do not mix a whole product milestone with tiny implementation steps as peers.
|
|
54
54
|
|
|
55
|
+
### Publish-first live acceptance
|
|
56
|
+
|
|
57
|
+
Classify each acceptance check **before planning Tasks**: pre-publish (verifiable in source/build/isolated runtime), live-only (requires newly published service, real account/provider/device or live traffic), or mandatory pre-release gate (security, data integrity, legal compliance or explicit approval).
|
|
58
|
+
|
|
59
|
+
- Complete pre-publish checks and independent immutable-head Final Review before Relay merge/delivery. **Never defer mandatory pre-release gates.** Do not create merge/deploy Tasks or infer delivery from model output.
|
|
60
|
+
- **Do not create a blocking pre-publish Task**, human escalation or repeated Planner round for live-only verification unavailable before publication. Record `NOT_RUN` or `PENDING_POST_PUBLISH` (never PASS), including residual risk; this does not constitute failed implementation.
|
|
61
|
+
- In the durable Plan `assessment`, provide a **post-publish acceptance handoff**: scenario, target release/version, evidence gap, risk, owner (`orchestrator` or `user`), prerequisites, and receipt-triggered follow-up. After actual publication, the orchestrator can run supported live tests or set up an authorized scheduled watcher/separate Job; otherwise request manual verification. **Never claim a watcher/reminder exists until it is actually created.**
|
|
62
|
+
- When only authorized live-only checks remain, pre-publish evidence and mandatory gates are complete, return `objective_status: "satisfied"` with `next_tasks: []` to reach Relay Final Review; preserve the handoff and `NOT_RUN` status. The code Job may complete, but live acceptance remains pending in the separate post-publish process.
|
|
63
|
+
- Preserve historical failed/deferred Tasks. Resolve them via supported cancellation/supersession and durable evidence/authorization, never silent deletion, invented success, or repeated E2E work. Diagnose version-mismatched Plan admission as a runtime issue instead of creating another live-only Task. After publication, defects require separate recovery/rollback work, not reopening a completed Job.
|
|
64
|
+
|
|
55
65
|
### Architecture Lens
|
|
56
66
|
|
|
57
67
|
When the resolved project context exposes a canonical design-principles
|
|
@@ -118,7 +128,7 @@ If evidence is absent or execution outcome is unknown, disposition that historic
|
|
|
118
128
|
|
|
119
129
|
- Prefer independently verifiable Tasks with stable IDs, but do not split work solely to make Tasks smaller.
|
|
120
130
|
- When a Task depends on mutable repository or product state, distinguish a frozen evidence target from the current execution head. A SHA may freeze that Task's own review/source evidence, but do not copy an upstream SHA into a dependent release, deploy, publication, or other follow-on Task unless the objective explicitly requires that same frozen target. After dependencies complete, downstream Tasks must resolve and verify the current durable Job/PR head before acting.
|
|
121
|
-
- When fresh UI, browser, store, runtime, or visual evidence is material to
|
|
131
|
+
- When fresh UI, browser, store, runtime, or visual evidence is material to a **pre-publish** Task, require current authentic evidence. If it is possible only after deployment, use the post-publish acceptance handoff above; existing screenshots or prior observations never substitute for live evidence.
|
|
122
132
|
- When a Job needs multi-perspective review, use the visible `review-chair` agent or an Agent Graph to select specialist roles dynamically. Keep specialist Tasks as independent siblings against the same immutable target/version, and leave worker/model/provider routing to Relay.
|
|
123
133
|
- A Task describes what an agent must accomplish; never emit a shell command as a worker Task.
|
|
124
134
|
- Use dependencies only for Task IDs inside the current Job, and only when execution order actually matters. Never encode cross-Job or cross-repository dependencies in `dependencies`.
|
|
@@ -13,6 +13,8 @@ Review exactly the immutable target/version specified by the Review Task. Do not
|
|
|
13
13
|
|
|
14
14
|
Reconstruct all material acceptance requirements from the durable Job objective and Task, then evaluate each with direct evidence. Check correctness, completeness, provenance, quality, regressions, explicit approvals and externally observable outcomes where applicable. Missing evidence is not PASS. If validation cannot complete, report task.failed. Keep review independent of implementation work.
|
|
15
15
|
|
|
16
|
+
For **publish-first live acceptance**, distinguish checks verifiable before release from checks that genuinely require the newly published runtime, real device, or external provider. A properly classified and handed-off live-only check is **NOT_RUN**, never PASS, but must not by itself cause a `task.failed` or `changes-required` verdict before publication. Verify that required pre-release quality/security/compliance/approval gates passed, that the future live test has a named owner and executable post-publish follow-up, and that remaining risks are disclosed. Missing mandatory pre-release evidence or a fabricated post-publish handoff remains blocking. Do not approve an unreviewed source/head or perform deployment yourself.
|
|
17
|
+
|
|
16
18
|
For spec-oriented delivery, select read-only `speckit-analyze` to check
|
|
17
19
|
`spec.md`, `plan.md`, and `tasks.md` consistency when those artifacts exist.
|
|
18
20
|
Use `speckit-checklist` only as requirements-quality guidance; do not create
|
|
@@ -54,4 +54,10 @@ For a managed Job, Relay owns Job completion. A satisfied Plan, successful imple
|
|
|
54
54
|
|
|
55
55
|
Post-merge publication and deployment activity is separate from Job lifecycle. Events or evidence such as `package.published`, published version metadata, service restart, and deployment verification may be attached after the Job is already `COMPLETED`; they must not hold the Job open, reopen it, or redefine completion. If post-merge deployment needs remediation, record that as separate deployment/recovery work rather than mutating the completed implementation Job lifecycle.
|
|
56
56
|
|
|
57
|
+
## Live acceptance after publication
|
|
58
|
+
|
|
59
|
+
Use **publish-first live acceptance** when verification genuinely requires a running published build, real provider/account, device, or runtime. The Planner completes available build/isolated tests and mandatory pre-merge gates, then hands off unrun live-only scenarios as explicit `NOT_RUN` / `PENDING_POST_PUBLISH` evidence, not successful tests. Do not let a live-only check become a pre-merge Task or repeated Plan round just because its environment is unavailable. Independent Final Review and normal Relay merge/delivery remain mandatory.
|
|
60
|
+
|
|
61
|
+
After a **verified** publication/deployment receipt, the orchestrator uses the handoff to run supported live checks and monitor health if capable and authorized. A persistent watcher requires a real scheduled automation/monitoring mechanism; never promise background execution without creating one. If the scenario requires a user action or unsupported device/account, provide a concrete manual-acceptance checklist and request/reminder rather than holding the completed code Job open. Record exact version, test owner, evidence and final status separately; failures trigger a new post-release fix/rollback workflow. Security, legal, data-loss and explicit pre-release approval requirements are **not** deferrable under this policy.
|
|
62
|
+
|
|
57
63
|
If a PR closes without merge, check the Job state through Relay CLI; do not infer a successful completion.
|
|
@@ -22,6 +22,8 @@ Use `job create` with standalone objective Markdown, or `job adopt` for an exist
|
|
|
22
22
|
Any task producer — orchestrator, planner, or nested task-producing agent — must follow this contract.
|
|
23
23
|
Task producers choose semantic task properties such as objective, dependencies, worker requirements, priority, and `storySize`. They do not normally choose an adapter, provider/model, or raw timeout milliseconds.
|
|
24
24
|
|
|
25
|
+
Before Task decomposition, distinguish tests achievable before publishing from live-only acceptance requiring the newly deployed runtime. The latter must be handed off for post-publish orchestrator or manual verification with an explicit `NOT_RUN`/`PENDING_POST_PUBLISH` status; do not create release-blocking Tasks for an unavailable future environment. Do not defer mandatory pre-publish security, compliance, or human approval gates. The authoritative policy and follow-up contract are in `agents/planner.agent.md` and `contracts/orchestrator-workflows.md`.
|
|
26
|
+
|
|
25
27
|
`Task.timeoutMs` is the inactivity window. Only an accepted `task.started` or newer `task.progress` event for the exact current execution resets it; duplicate, stale, and out-of-order progress does not.
|
|
26
28
|
|
|
27
29
|
### Planning graph and semantic Task tree
|
|
@@ -66,6 +68,8 @@ This is a worker result-content contract, not a requirement for dedicated `rootC
|
|
|
66
68
|
|
|
67
69
|
Keep these concepts distinct: observation is not root cause; hypothesis is not root cause; requested approach is not implemented solution; implementation is not validation.
|
|
68
70
|
|
|
71
|
+
Reviewers apply the same publish-first evidence boundary: they must not call a post-publish live-only test PASS, but may approve pre-publish implementation when all mandatory pre-release gates pass and deferred scenarios have an explicit owner, evidence gap, risk and actionable handoff. Missing mandatory pre-publish evidence still blocks approval. No reviewer may authorize an unverified merge or treat an unevaluated provider receipt as success.
|
|
72
|
+
|
|
69
73
|
### Worker self-review before success
|
|
70
74
|
|
|
71
75
|
Every artifact-changing implementation worker follows the shared [worker self-review loop](worker-self-review.md), regardless of its selected agent name or runtime adapter. Complete the implement → self-review → fix → re-review cycle until the latest full review has no actionable findings. Include review rounds, fixes, validation evidence, and the clean-review result in the durable Task result. The worker's self-review never substitutes for an independent final Reviewer, human approval, or Relay's Graph-owned lifecycle gates.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Plan Apply Convergence Validation
|
|
3
|
-
description: Validates
|
|
3
|
+
description: Validates Plan objective completion and, for Force Restate, historical consistency before the atomic commit action. Explicitly resolved cancel_supersede Tasks and failed Tasks classified superseded by a succeeded target are historical evidence, not unfinished implementation.
|
|
4
4
|
---
|
|
5
5
|
flowchart LR
|
|
6
6
|
%% relay: initial idle
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Review Lifecycle
|
|
3
|
-
description: Manages review creation, immutable verdicts, changes-required, and re-review.
|
|
3
|
+
description: Manages review creation, immutable verdicts, changes-required, and re-review. The implementationComplete guard ignores only durably resolved cancel_supersede cancellations and failed Tasks with a valid superseded classification targeting succeeded work.
|
|
4
4
|
---
|
|
5
5
|
flowchart LR
|
|
6
6
|
%% relay: initial none
|
|
@@ -24,9 +24,8 @@ depUnsat["guard: dependenciesUnsatisfied"]
|
|
|
24
24
|
runnable["guard: runnable"]
|
|
25
25
|
dispatchable["guard: dispatchable"]
|
|
26
26
|
shortcutExecution["guard: shortcutExecution"]
|
|
27
|
-
shortcutFallback["guard: shortcutFallback"]
|
|
28
27
|
shortcutHasGraph["guard: shortcutHasGraph"]
|
|
29
|
-
|
|
28
|
+
shortcutDirectInvocation["guard: shortcutDirectInvocation"]
|
|
30
29
|
recoverStart["guard: recoverableExecution"]
|
|
31
30
|
recoverComplete["guard: recoverableExecution"]
|
|
32
31
|
recoverBlocked["guard: recoverableExecution"]
|
|
@@ -37,11 +36,12 @@ recoveryReopenClearError["action: mutation.clearError"]
|
|
|
37
36
|
recoveryReopenClearReason["action: mutation.clearFailureReason"]
|
|
38
37
|
recoveryReopenClearLease["action: mutation.clearLease"]
|
|
39
38
|
recoveryReopenClearExecution["action: mutation.clearExecution"]
|
|
40
|
-
shortcutWorkerFallback["action: mutation.markShortcutWorkerFallback"]
|
|
41
39
|
shortcutRecoveryRequired["action: mutation.markShortcutRecoveryRequired"]
|
|
42
40
|
|
|
43
41
|
plannerRetryAvailable["guard: retryAvailable"]
|
|
44
42
|
platformFallbackSafe["guard: platformFallbackSafe"]
|
|
43
|
+
noStartFallbackAllowed["guard: noStartFallbackAllowed"]
|
|
44
|
+
prepareNoStartFallback["action: mutation.prepareNoStartFallback"]
|
|
45
45
|
preparePlatformFallback["action: mutation.preparePlatformFallback"]
|
|
46
46
|
plannerUnavailableMark["action: mutation.markPlannerUnavailable"]
|
|
47
47
|
orphanFailMark["action: mutation.markUnknownOutcome"]
|
|
@@ -113,12 +113,12 @@ runnable -->|true| reconcileQueuedClearError
|
|
|
113
113
|
reconcileQueuedClearError --> reconcileQueuedClearReason
|
|
114
114
|
reconcileQueuedClearReason --> queued
|
|
115
115
|
queued -->|on: dispatch| shortcutExecution
|
|
116
|
-
shortcutExecution -->|true|
|
|
116
|
+
shortcutExecution -->|true| shortcutHasGraph
|
|
117
117
|
shortcutExecution -->|false| dispatchable
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
shortcutHasGraph -->|false|
|
|
118
|
+
shortcutHasGraph -->|true| shortcutDirectInvocation
|
|
119
|
+
shortcutDirectInvocation -->|true| shortcutLaunch
|
|
120
|
+
shortcutDirectInvocation -->|false| queued
|
|
121
|
+
shortcutHasGraph -->|false| queued
|
|
122
122
|
dispatchable -->|true| dispatchLaunch
|
|
123
123
|
dispatchLaunch --> queued
|
|
124
124
|
shortcutLaunch --> queued
|
|
@@ -146,6 +146,10 @@ queued -->|on: effect.launchShortcut.failed| failed
|
|
|
146
146
|
queued -->|on: watchdog.failed| failed
|
|
147
147
|
queued -->|on: worker.delivery_failed| failed
|
|
148
148
|
queued -->|on: worker.start_ack_failed| failed
|
|
149
|
+
queued -->|on: worker.no_start_failed| noStartFallbackAllowed
|
|
150
|
+
noStartFallbackAllowed -->|true| prepareNoStartFallback
|
|
151
|
+
prepareNoStartFallback --> queued
|
|
152
|
+
noStartFallbackAllowed -->|false| failed
|
|
149
153
|
queued -->|on: worker.platform_failure| platformFallbackSafe
|
|
150
154
|
platformFallbackSafe -->|true| preparePlatformFallback
|
|
151
155
|
preparePlatformFallback --> queued
|
|
@@ -193,10 +197,7 @@ running -->|on: task.completed| completeClearError
|
|
|
193
197
|
completeClearError --> completeClearReason
|
|
194
198
|
completeClearReason --> succeeded
|
|
195
199
|
running -->|on: task.failed| failed
|
|
196
|
-
running -->|on: shortcut.failed|
|
|
197
|
-
shortcutEffectsSafe -->|true| shortcutWorkerFallback
|
|
198
|
-
shortcutWorkerFallback --> failed
|
|
199
|
-
shortcutEffectsSafe -->|false| shortcutRecoveryRequired
|
|
200
|
+
running -->|on: shortcut.failed| shortcutRecoveryRequired
|
|
200
201
|
shortcutRecoveryRequired --> failed
|
|
201
202
|
running -->|on: worker.platform_failure| runningPlatformFailureQuarantine
|
|
202
203
|
runningPlatformFailureQuarantine["action: mutation.quarantinePlatformFailure"]
|
|
@@ -9,7 +9,6 @@ checkOwner["state: check_owner"]
|
|
|
9
9
|
checkPath["state: check_path"]
|
|
10
10
|
checkFreshExecution["state: check_fresh_execution"]
|
|
11
11
|
activeRecovery["action: resolution.activateRecovery"]
|
|
12
|
-
shortcutWorkerFallback["action: resolution.activateShortcutWorkerFallback"]
|
|
13
12
|
sameJob["action: resolution.attachSameJobDependency"]
|
|
14
13
|
blockerJob["action: resolution.registerBlockerDependency"]
|
|
15
14
|
escalate["action: resolution.createEscalationGate"]
|
|
@@ -19,7 +18,6 @@ rejected["state: rejected"]
|
|
|
19
18
|
recoveryOwner["guard: recoveryOwnerAvailable"]
|
|
20
19
|
plannerOwner["guard: plannerOwnerAvailable"]
|
|
21
20
|
exact["guard: exactOriginalRetry"]
|
|
22
|
-
shortcutInterrupted["guard: shortcutInterrupted"]
|
|
23
21
|
same["guard: sameJobDependency"]
|
|
24
22
|
fresh["guard: freshRecoveryExecution"]
|
|
25
23
|
blocker["guard: blockerJobDependency"]
|
|
@@ -42,9 +40,7 @@ checkPath -->|on: resolution.propose| fresh
|
|
|
42
40
|
fresh -->|true| checkFreshExecution
|
|
43
41
|
fresh -->|false| rejected
|
|
44
42
|
checkFreshExecution -->|on: resolution.propose| exact
|
|
45
|
-
exact -->|true|
|
|
46
|
-
shortcutInterrupted -->|true| shortcutWorkerFallback
|
|
47
|
-
shortcutInterrupted -->|false| activeRecovery
|
|
43
|
+
exact -->|true| activeRecovery
|
|
48
44
|
exact -->|false| same
|
|
49
45
|
same -->|true| sameJob
|
|
50
46
|
same -->|false| blocker
|
|
@@ -55,7 +51,6 @@ gate -->|false| obsoleteGuard
|
|
|
55
51
|
obsoleteGuard -->|true| obsolete
|
|
56
52
|
obsoleteGuard -->|false| rejected
|
|
57
53
|
activeRecovery -->|to: resolved| resolved
|
|
58
|
-
shortcutWorkerFallback -->|to: resolved| resolved
|
|
59
54
|
sameJob -->|to: resolved| resolved
|
|
60
55
|
blockerJob -->|to: resolved| resolved
|
|
61
56
|
escalate -->|to: resolved| resolved
|