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.
Files changed (36) hide show
  1. package/dist/adapters.js +2 -1
  2. package/dist/agent-shortcut.js +113 -41
  3. package/dist/browser-worker-runtime.js +7 -2
  4. package/dist/chatgpt-platform-fallback.js +30 -0
  5. package/dist/cli-shortcut-local.js +49 -0
  6. package/dist/cli-shortcut.js +81 -19
  7. package/dist/cli.js +8 -3
  8. package/dist/force-restate-validation.js +3 -1
  9. package/dist/job-execution-slot.js +4 -1
  10. package/dist/model-routing.js +8 -0
  11. package/dist/reconciler-review.js +32 -13
  12. package/dist/reconciler-runtime.js +43 -54
  13. package/dist/reconciler.js +12 -2
  14. package/dist/relay-job-snapshot-reads.js +5 -2
  15. package/dist/relay-workflow-operations.js +1 -1
  16. package/dist/runtime-status.js +11 -4
  17. package/dist/shortcut-node-worker.js +128 -0
  18. package/dist/shortcut-stage-contract.js +50 -0
  19. package/dist/shortcut-worker-runner.js +73 -0
  20. package/dist/task-actions.js +4 -13
  21. package/dist/task-inactivity-watchdog.js +7 -0
  22. package/dist/terminal-event-recovery.js +13 -0
  23. package/dist/worker-failure-recovery.js +89 -0
  24. package/dist/workflow/contracts.js +4 -0
  25. package/dist/workflow/definitions-v2.js +2 -0
  26. package/dist/workflow/runtime.js +30 -0
  27. package/dist/workflow/task-resolution.js +1 -4
  28. package/package.json +4 -3
  29. package/skills/agents-relay/agents/planner.agent.md +14 -4
  30. package/skills/agents-relay/agents/reviewer.agent.md +2 -0
  31. package/skills/agents-relay/contracts/orchestrator-workflows.md +6 -0
  32. package/skills/agents-relay/contracts/task-job-contract.md +4 -0
  33. package/workflow/force-restate-validation.mmd +1 -1
  34. package/workflow/review-lifecycle.mmd +1 -1
  35. package/workflow/task-lifecycle.mmd +13 -12
  36. package/workflow/task-resolution.mmd +1 -6
@@ -1,6 +1,7 @@
1
1
  import { classifyTaskResolution } from './workflow/task-resolution.js';
2
2
  import { tryTransitionTaskEvent } from './task-transitions.js';
3
3
  import { satisfiesWorker } from './worker-routing.js';
4
+ import { isSuperseded } from './runtime-status.js';
4
5
  function dependencySatisfied(task, byId) {
5
6
  return task.dependencies.every(id => {
6
7
  const dependency = byId.get(id);
@@ -74,8 +75,9 @@ export function objectiveSatisfiedForReview(job) {
74
75
  const latest = (job.plans ?? []).at(-1);
75
76
  if (latest?.status !== 'SUCCEEDED' || latest.objectiveStatus !== 'satisfied')
76
77
  return false;
78
+ const byId = new Map(job.tasks.map(task => [task.id, task]));
77
79
  const implementation = job.tasks.filter(task => task.kind !== 'planner' && task.agentName !== 'reviewer' && task.agentName !== 'troubleshooter'
78
- && task.resolutionClassification?.kind !== 'superseded');
80
+ && !isSuperseded(task, byId));
79
81
  return implementation.length > 0 && implementation.every(task => task.state === 'SUCCEEDED');
80
82
  }
81
83
  /** Apply Planner-proposed history dispositions to a private candidate snapshot.
@@ -8,11 +8,14 @@ export function jobHasActiveExecution(job, except = {}) {
8
8
  if (task.id === except.taskId)
9
9
  return false;
10
10
  const shortcut = task.result?.data?.shortcut;
11
+ const delegatedWorker = job.executionMode === 'shortcut' && job.contentOnly === true && task.state === 'RUNNING'
12
+ && task.result?.data?.shortcut && typeof task.result.data.shortcut === 'object'
13
+ && Object.keys(task.result.data.shortcut.workerNodes ?? {}).length > 0;
11
14
  const durableWait = job.executionMode === 'shortcut' && job.contentOnly === true && task.state === 'RUNNING'
12
15
  && task.leaseOwner === null && shortcut && typeof shortcut === 'object'
13
16
  && shortcut.waits
14
17
  && Object.keys(shortcut.waits).length > 0;
15
- return !durableWait && (task.state === 'RUNNING' || (task.executionId !== null && !['SUCCEEDED', 'FAILED', 'CANCELLED'].includes(task.state)));
18
+ return !durableWait && !delegatedWorker && (task.state === 'RUNNING' || (task.executionId !== null && !['SUCCEEDED', 'FAILED', 'CANCELLED'].includes(task.state)));
16
19
  });
17
20
  const planner = (job.plans ?? []).some(plan => plan.id !== except.planId
18
21
  && plan.executionId !== null && plan.status === 'PLANNING');
@@ -71,6 +71,14 @@ async function readConfig(path) {
71
71
  return null;
72
72
  }
73
73
  }
74
+ /** Only a real top-level Codex config model counts as a configured default. */
75
+ export async function configuredCodexDefault(codexHome = process.env.CODEX_HOME ?? join(homedir(), '.codex')) {
76
+ const config = await readConfig(join(codexHome, 'config.toml'));
77
+ return config?.model
78
+ ? { provider: config.provider ?? 'openai', model: config.model,
79
+ ...(config.reasoning ? { reasoning: config.reasoning } : {}) }
80
+ : null;
81
+ }
74
82
  function withResource(candidate, usage) {
75
83
  const resource = usageForProvider(usage, candidate.provider);
76
84
  return { ...candidate, resourceHealthy: resource.healthy, resourceUsedPercent: resource.usedPercent, resourceRemainingPercent: resource.remainingPercent, resourceResetAt: resource.resetAt, resourceResetInMinutes: resource.resetInMinutes, resourceWindows: resource.windows };
@@ -13,7 +13,7 @@ import { createTaskEntity } from './workflow/entity-creation.js';
13
13
  import { localSourceHead, localWorkingHead } from './local-git-merge.js';
14
14
  import { chatgptThreadRequirements, resolveReviewerThreadDestination, resolveImplementationTaskThreadDestination, prepareReviewerThreadDelivery } from './reviewer-thread.js';
15
15
  import { reviewGenerationMatches } from './review-generation-fence.js';
16
- import { quarantineUnavailableCodexFallback } from './chatgpt-platform-fallback.js';
16
+ import { codexNoStartFallbackRoute, quarantineUnavailableCodexFallback } from './chatgpt-platform-fallback.js';
17
17
  export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
18
18
  async currentHeadSha(job) {
19
19
  // Tests may replace the external Git effect entirely; in that case its
@@ -315,18 +315,22 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
315
315
  : [];
316
316
  const taskExcludedRoutes = (task.routingExclusions ?? []).map(item => ({ provider: item.provider, model: item.model, profile: item.profile }));
317
317
  const excludedRoutes = [...taskExcludedRoutes, ...parentExcludedRoutes];
318
- const routed = await routeExecution(candidates, requirements, {
319
- decisionEngine: this.options.decisionEngine,
320
- decisionMode: this.options.decisionMode,
321
- taskFacts: { ...taskFacts, recovery: task.recoveryContext ?? null, recovery_parent_failed_route: excludedRoutes[0] ?? null },
322
- usage,
323
- registered,
324
- chatgptRunning: runtimeSummary?.chatgptRunning ?? 0,
325
- routingConstraints,
326
- excludedRoutes,
327
- auditStore: this.options.decisionAuditStore,
328
- auditTask: task,
329
- });
318
+ const routed = task.noStartFallback
319
+ ? await codexNoStartFallbackRoute(task, this.options.adapters, registered, usage)
320
+ : await routeExecution(candidates, requirements, {
321
+ decisionEngine: this.options.decisionEngine,
322
+ decisionMode: this.options.decisionMode,
323
+ taskFacts: { ...taskFacts, recovery: task.recoveryContext ?? null, recovery_parent_failed_route: excludedRoutes[0] ?? null },
324
+ usage,
325
+ registered,
326
+ chatgptRunning: runtimeSummary?.chatgptRunning ?? 0,
327
+ routingConstraints,
328
+ excludedRoutes,
329
+ auditStore: this.options.decisionAuditStore,
330
+ auditTask: task,
331
+ });
332
+ if (!routed)
333
+ throw new Error('Codex configured default unavailable for no-start recovery');
330
334
  task.workerSelection = routed.selection;
331
335
  task.adapter = routed.candidate.adapter;
332
336
  task.routing = routed.candidate.routing;
@@ -342,6 +346,21 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
342
346
  return await this.routeTaskForExecution(job, task);
343
347
  }
344
348
  catch (error) {
349
+ if (task.noStartFallback) {
350
+ const message = error instanceof Error ? error.message : String(error);
351
+ const transition = await this.taskTransitions.apply(job.id, task.id, 'fail', {
352
+ eligible: (_job, current) => current.state === 'QUEUED'
353
+ && current.executionId === null
354
+ && current.noStartFallback?.failedExecutionId === task.noStartFallback?.failedExecutionId,
355
+ mutate: (_job, current) => {
356
+ current.error = 'Codex default fallback route unavailable: ' + message;
357
+ current.failureReason = 'codex_default_fallback_unavailable';
358
+ },
359
+ });
360
+ if (transition?.decision.accepted)
361
+ await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.failed', 'failed', transition.task.error ?? message, 'user', { reason: 'codex_default_fallback_unavailable' }, { agent: 'relay', component: 'agents-relay' }));
362
+ return undefined;
363
+ }
345
364
  if (!['chatgpt', 'z'].includes(task.adapter) || !task.platformFailure?.safeToReroute)
346
365
  throw error;
347
366
  await quarantineUnavailableCodexFallback(this.taskTransitions, event => this.emit(event), job.id, task.id, error);
@@ -1,13 +1,13 @@
1
- import { hasSafeAlternativeWorker } from './browser-worker-routing.js';
1
+ import { handleWorkerLaunchFailure } from './worker-failure-recovery.js';
2
2
  import { normalizeReviewerTerminalEvent } from './review-terminal-normalization.js';
3
3
  import { executionEventSource, eventSourceId, executionIdFromSource, claimTerminalExecution, terminalExecutionClaimed } from './execution-event-identity.js';
4
4
  export { executionEventSource } from './execution-event-identity.js';
5
5
  import { applyJobEffectOutcomes, applyTaskEffectOutcomes } from './workflow-effect-failures.js';
6
- import { classifyChatGptPlatformFailure, classifyWorkerRejection, reroutableWorkerRejections } from './worker-rejection.js';
6
+ import { classifyWorkerRejection, reroutableWorkerRejections } from './worker-rejection.js';
7
7
  import { applyTaskRetryAction } from './task-actions.js';
8
8
  import { DurableTaskTransitionRuntime } from './workflow/durable-transition.js';
9
9
  import { eventFor } from './events.js';
10
- import { recordTerminalRouteOutcome, recordLaunchRouteOutcome, recordWatchdogRouteOutcome } from './route-outcome-recording.js';
10
+ import { recordTerminalRouteOutcome, recordWatchdogRouteOutcome } from './route-outcome-recording.js';
11
11
  import { WorkflowEffectExecutor } from './workflow/effects.js';
12
12
  import { ReconcileCoordinator } from './reconcile-coordinator.js';
13
13
  import { acceptedReportedTag, eventDataWithoutTag } from './task-tag.js';
@@ -15,7 +15,6 @@ import { createWorkerStartAck } from './worker-start-ack.js';
15
15
  import { monitorExecutionProcess } from './execution-process-tracker.js';
16
16
  import { HostInteractiveInvocationCoordinator, hostInvocationPorts } from './interactive-invocation.js';
17
17
  import { resumeInteractiveTask } from './interactive-resume.js';
18
- import { persistChatGptPlatformFailure } from './chatgpt-platform-fallback.js';
19
18
  import { acceptTaskProgress, armInactivityWatchdog, inactivityDeadline, isCorrelatedWorkerEvent, isRecoverableWatchdogFailure } from './task-inactivity-watchdog.js';
20
19
  const activeExecutionOwners = new Map();
21
20
  import { withExecutionBoundary } from './execution-boundary.js';
@@ -256,57 +255,26 @@ export class ReconcilerRuntimeBase {
256
255
  return true;
257
256
  }
258
257
  async failLaunch(jobId, taskId, executionId, failure, phase = 'launch') {
259
- const message = failure instanceof Error ? failure.message : String(failure);
260
- const currentJob = await this.store.load(jobId);
261
- const currentTask = currentJob.tasks.find(task => task.id === taskId);
262
- const alternative = hasSafeAlternativeWorker(currentTask, this.options.adapters, await this.store.listAgents(), this.options.usageSnapshotProvider ? await this.options.usageSnapshotProvider() : undefined);
263
- const activeExecution = this.live.get(taskId);
264
- const platformFailure = (currentTask?.adapter === 'chatgpt' || currentTask?.adapter === 'z') ? classifyChatGptPlatformFailure(failure, phase) : undefined;
265
- const unknownOutcome = phase === 'start-ack' || ['outcome_unknown', 'start_ack_timeout'].includes(platformFailure?.classification ?? '')
266
- || (phase === 'delivery' && activeExecution?.executionId === executionId && activeExecution.workerStarted);
267
- const failureReason = phase === 'start-ack' ? 'worker_start_timeout'
268
- : /WEBHELM_UNAVAILABLE|webhelm runtime dependency unavailable|webhelm session start returned no session_id|no close frame received or sent/i.test(message)
269
- ? 'browser_workspace_unavailable'
270
- : undefined;
271
- const claim = executionId ?? `${jobId}:${taskId}`;
272
- if (this.launchFailureClaims.has(claim))
273
- return;
274
- this.launchFailureClaims.add(claim);
275
- const cleanup = setTimeout(() => this.launchFailureClaims.delete(claim), 60000);
276
- cleanup.unref();
277
- const workflowEvent = platformFailure ? 'worker.platform_failure' : phase === 'start-ack' ? 'worker.start_ack_failed' : 'worker.delivery_failed';
278
- const transition = await this.taskTransitions.apply(jobId, taskId, platformFailure ? 'worker.platform_failure' : workflowEvent, {
279
- eligible: (_job, task) => task.executionId === executionId,
280
- facts: () => ({ platformFallbackSafe: platformFailure?.safeToReroute === true && alternative }),
281
- mutate: (_job, task, decision) => {
282
- if (platformFailure)
283
- persistChatGptPlatformFailure(task, currentTask, executionId, platformFailure.classification, platformFailure.evidence, platformFailure.safeToReroute);
284
- task.error = decision.target === 'QUEUED' ? null : `Worker ${phase} failed: ${message}`;
285
- task.failureReason = decision.target === 'QUEUED' ? undefined : unknownOutcome
286
- ? 'worker_outcome_unknown' : platformFailure ? 'worker_platform_failure' : failureReason;
287
- task.leaseOwner = null;
288
- task.leaseExpiresAt = null;
289
- task.executionId = null;
258
+ await handleWorkerLaunchFailure({
259
+ store: this.store,
260
+ adapters: this.options.adapters,
261
+ usageSnapshotProvider: this.options.usageSnapshotProvider,
262
+ decisionAuditStore: this.options.decisionAuditStore,
263
+ taskTransitions: this.taskTransitions,
264
+ live: id => this.live.get(id),
265
+ launchFailureClaims: this.launchFailureClaims,
266
+ clearExecution: (id, execution) => this.clearExecution(id, execution),
267
+ clearTerminalWaiter: (id, execution) => {
268
+ const waiter = this.terminalWaiters.get(id);
269
+ if (waiter?.executionId === execution) {
270
+ waiter.resolve();
271
+ this.terminalWaiters.delete(id);
272
+ }
290
273
  },
291
- });
292
- if (!transition)
293
- return;
294
- if (!transition.decision.accepted) {
295
- await this.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' }));
296
- return;
297
- }
298
- await recordLaunchRouteOutcome(this.options.decisionAuditStore, transition.task, message, phase, executionId, unknownOutcome);
299
- if (executionId) {
300
- const live = this.live.get(taskId);
301
- if (live?.executionId === executionId) {
302
- live.controller.abort();
303
- live.execution.cancel();
304
- this.clearExecution(taskId, executionId);
305
- }
306
- }
307
- const event = eventFor(jobId, taskId, transition.task.parentTaskId, 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, ...(transition.task.platformFailure ? { platformFailure: transition.task.platformFailure } : {}) }, { agent: 'relay', component: 'agents-relay', watchdog: true });
308
- this.detach(this.emit(event), jobId, taskId, 'worker failure event');
309
- this.detach(this.eventCoordinator.accept({ jobId, reason: `worker-${phase}-failure` }), jobId, taskId, 'worker failure reconcile wake');
274
+ emit: event => this.emit(event),
275
+ detach: (promise, job, task, context) => this.detach(promise, job, task, context),
276
+ wake: (job, task, reason) => this.detach(this.eventCoordinator.accept({ jobId: job, reason }), job, task, 'worker failure reconcile wake'),
277
+ }, jobId, taskId, executionId, failure, phase);
310
278
  }
311
279
  async runtimeSettled(jobId, taskId, executionId, result, error) {
312
280
  const live = this.live.get(taskId);
@@ -318,6 +286,12 @@ export class ReconcilerRuntimeBase {
318
286
  const task = job.tasks.find(item => item.id === taskId);
319
287
  if (!task)
320
288
  return;
289
+ if (error && ['chatgpt', 'z'].includes(task.adapter)
290
+ && task.executionId === executionId && task.state === 'QUEUED'
291
+ && !live?.workerStarted) {
292
+ await this.failLaunch(jobId, taskId, executionId, error, 'process');
293
+ return;
294
+ }
321
295
  if (task.adapter !== 'chatgpt' && task.adapter !== 'z') {
322
296
  const exited = await this.taskTransitions.updateFact(jobId, taskId, current => current.executionId === executionId && ['RUNNING', 'QUEUED'].includes(current.state), current => { current.processExitedAt = new Date().toISOString(); });
323
297
  if (exited)
@@ -341,6 +315,11 @@ export class ReconcilerRuntimeBase {
341
315
  return;
342
316
  }
343
317
  const live = this.live.get(taskId);
318
+ if ((current.adapter === 'chatgpt' || current.adapter === 'z')
319
+ && current.state === 'QUEUED' && !live?.workerStarted) {
320
+ await this.failLaunch(jobId, taskId, executionId, new Error('Worker failed to publish task.started before the inactivity deadline'), 'start-ack');
321
+ return;
322
+ }
344
323
  // Do not cancel before the serialized watchdog transition rechecks the
345
324
  // deadline: a concurrent accepted progress event may have extended it.
346
325
  const exit = live?.executionId === executionId && live.processSettled ? live.execution.processExit : undefined;
@@ -400,6 +379,16 @@ export class ReconcilerRuntimeBase {
400
379
  }
401
380
  }
402
381
  async applyTerminalEvent(event, trustedInternal = false) {
382
+ if (event.type === 'task.failed') {
383
+ const job = await this.store.load(event.job_id);
384
+ const original = job.tasks.find(task => task.id === event.task_id);
385
+ if (original && ['chatgpt', 'z'].includes(original.adapter)
386
+ && original.state === 'QUEUED' && original.executionId
387
+ && isCorrelatedWorkerEvent(original, event)) {
388
+ await this.failLaunch(event.job_id, event.task_id, original.executionId, new Error(event.message || 'Worker reported failure before task.started'), 'terminal');
389
+ return { applied: true, reconcile: false, reason: 'task.failed.no-start-fallback' };
390
+ }
391
+ }
403
392
  const liveAtTerminal = this.live.get(event.task_id);
404
393
  const terminalEventExecutionId = executionIdFromSource(eventSourceId(event), event.job_id, event.task_id);
405
394
  const lifecycleEvent = event.type === 'task.blocked'
@@ -27,6 +27,7 @@ import { exhaustedTroubleshooterRecoveries, pendingTroubleshooterTasks, pendingT
27
27
  import { fallbackFailedTroubleshooters, escalateExhaustedTroubleshooters } from './troubleshooter-fallback.js';
28
28
  import { cleanupMergedJobWorktree } from './job-worktree-cleanup.js';
29
29
  import { jobHasActiveExecution } from './job-execution-slot.js';
30
+ import { requiresWorkerInactivityWatchdog } from './task-inactivity-watchdog.js';
30
31
  import { managedWorkerInput } from './managed-worker-input.js';
31
32
  import { launchShortcutEffect, resumeShortcutEffect, resumeShortcutEventWaits } from './reconciler-shortcut.js';
32
33
  export { managedWorkerInput } from './managed-worker-input.js';
@@ -58,6 +59,10 @@ export class Reconciler extends ReconcilerReviewBase {
58
59
  }
59
60
  async dispatchExecutableTasks(jobId) {
60
61
  const scheduled = refreshTaskDependencies(await this.store.load(jobId));
62
+ // Ordinary daemon/queue never owns Shortcut Jobs, including recovery Tasks.
63
+ // Only the explicit foreground runner may use existing Worker Adapters.
64
+ if (scheduled.executionMode === 'shortcut' && !this.options.shortcutRunnerOwner)
65
+ return scheduled;
61
66
  if (scheduled.pause)
62
67
  return scheduled;
63
68
  for (const task of scheduled.tasks.filter(item => item.state === 'SUCCEEDED' && (item.continuation || scheduled.continuation) && !item.continuationDeliveredAt)) {
@@ -74,7 +79,7 @@ export class Reconciler extends ReconcilerReviewBase {
74
79
  .slice(0, Math.min(capacity, 1));
75
80
  for (const task of dispatchable) {
76
81
  const shortcut = task.result?.data?.shortcut;
77
- await transitionTaskEvent(task, 'dispatch', { dispatchable: true, shortcutExecution: scheduled.executionMode === 'shortcut' && scheduled.contentOnly === true, shortcutFallback: shortcut?.workerFallback === true, shortcutHasGraph: Boolean(task.agentGraph) }, async (actionId) => {
82
+ await transitionTaskEvent(task, 'dispatch', { dispatchable: true, shortcutExecution: scheduled.executionMode === 'shortcut' && scheduled.contentOnly === true && shortcut?.workerFallback !== true && Boolean(task.agentGraph), shortcutFallback: shortcut?.workerFallback === true, shortcutHasGraph: Boolean(task.agentGraph) }, async (actionId) => {
78
83
  const outcomes = await this.workflowEffects.execute([actionId], { jobId: scheduled.id, taskId: task.id, transitionKey: `dispatch:${task.attempt}`, data: { attempt: task.attempt } });
79
84
  await this.applyTaskEffectOutcomes(scheduled, task, outcomes);
80
85
  }, async () => { await this.store.saveTask(task); });
@@ -87,6 +92,10 @@ export class Reconciler extends ReconcilerReviewBase {
87
92
  this.reconciling = true;
88
93
  try {
89
94
  let job = await this.store.load(jobId);
95
+ // The same durable Job flag covers children, retries, and Troubleshooters.
96
+ // Do not let a background Reconciler mutate or dispatch any of them.
97
+ if (job.executionMode === 'shortcut' && !this.options.shortcutRunnerOwner)
98
+ return job;
90
99
  await drainProductionWorkflowOutbox(this.store, this.options);
91
100
  await deliverPendingEscalations(this.store, jobId, this.options.escalationNotifier);
92
101
  job = await this.store.load(jobId);
@@ -178,7 +187,8 @@ export class Reconciler extends ReconcilerReviewBase {
178
187
  const taskStatesBeforeSchedule = new Map(beforeSchedule.tasks.map(task => [task.id, task.state]));
179
188
  let scheduled = refreshTaskDependencies(beforeSchedule);
180
189
  for (const task of scheduled.tasks)
181
- if (task.executionId && ['QUEUED', 'RUNNING'].includes(task.state))
190
+ if (task.executionId && ['QUEUED', 'RUNNING'].includes(task.state)
191
+ && requiresWorkerInactivityWatchdog(scheduled, task))
182
192
  this.armInactivityWatchdog(task, task.executionId);
183
193
  for (const task of scheduled.tasks) {
184
194
  if (taskStatesBeforeSchedule.get(task.id) !== task.state)
@@ -1,8 +1,11 @@
1
1
  import { normalizeLegacyTaskLifecycle } from './types.js';
2
2
  import { normalizeLegacyJobPrNumber } from './job-pr-number-migration.js';
3
3
  export function currentJobMetadata(job) {
4
- const { schedule: _schedule, ...current } = job;
5
- return current;
4
+ // Retired historical modes must not survive reads or writes. Only the
5
+ // supported opt-in Direct Shortcut mode is part of the active Job contract.
6
+ const { schedule: _schedule, executionMode, ...current } = job;
7
+ return (executionMode === 'shortcut'
8
+ ? { ...current, executionMode: 'shortcut' } : current);
6
9
  }
7
10
  export function normalizeRelayJob(json) {
8
11
  const job = currentJobMetadata(normalizeLegacyJobPrNumber(JSON.parse(json)));
@@ -86,7 +86,7 @@ export class SQLiteWorkflowOperations {
86
86
  const job = JSON.parse(row.json);
87
87
  const task = job.tasks.find(item => item.id === identity.taskId);
88
88
  const shortcut = task?.result?.data?.shortcut;
89
- const decision = dispatchWorkflowGraphSync(taskLifecycleV2, { initialState: 'QUEUED', input: { transport: 'event', id: 'dispatch', payload: {} }, durableFacts: { dispatchable: true, shortcutExecution: job.executionMode === 'shortcut' && job.contentOnly === true, shortcutFallback: shortcut?.workerFallback === true, shortcutHasGraph: Boolean(task?.agentGraph) } });
89
+ const decision = dispatchWorkflowGraphSync(taskLifecycleV2, { initialState: 'QUEUED', input: { transport: 'event', id: 'dispatch', payload: {} }, durableFacts: { dispatchable: true, shortcutExecution: job.executionMode === 'shortcut' && job.contentOnly === true && shortcut?.workerFallback !== true && Boolean(task?.agentGraph), shortcutFallback: shortcut?.workerFallback === true, shortcutHasGraph: Boolean(task?.agentGraph), shortcutDirectInvocation: job.executionMode === 'shortcut' && job.contentOnly === true } });
90
90
  if (!decision.accepted)
91
91
  throw new Error('canonical Task Graph did not authorize launch');
92
92
  const actionId = decision.actions.find(action => action.id === 'effect.launchTask' || action.id === 'effect.launchShortcut')?.id;
@@ -1,12 +1,19 @@
1
- function isSuperseded(task) {
2
- return task.state === 'CANCELLED' && ((task.resolution?.path === 'cancel_supersede' && task.resolution.state === 'resolved')
3
- || (typeof task.error === 'string' && task.error.startsWith('Superseded ')));
1
+ export function isSuperseded(task, byId) {
2
+ if (task.state === 'CANCELLED' && task.resolution?.path === 'cancel_supersede' && task.resolution.state === 'resolved')
3
+ return true;
4
+ const classification = task.resolutionClassification;
5
+ return task.state === 'FAILED' && classification?.kind === 'superseded'
6
+ && typeof classification.targetTaskId === 'string' && Boolean(classification.targetTaskId.trim())
7
+ && typeof classification.evidence === 'string' && Boolean(classification.evidence.trim())
8
+ && typeof classification.reason === 'string' && Boolean(classification.reason.trim())
9
+ && byId.get(classification.targetTaskId)?.state === 'SUCCEEDED';
4
10
  }
5
11
  export function implementationTasks(job) {
12
+ const byId = new Map(job.tasks.map(task => [task.id, task]));
6
13
  return job.tasks.filter(task => task.kind !== 'planner'
7
14
  && task.agentName !== 'reviewer'
8
15
  && task.agentName !== 'troubleshooter'
9
- && !isSuperseded(task)
16
+ && !isSuperseded(task, byId)
10
17
  && task.state !== 'DRAFT');
11
18
  }
12
19
  export function implementationComplete(job) {
@@ -0,0 +1,128 @@
1
+ import { mkdir, readFile } from 'node:fs/promises';
2
+ import { dirname, isAbsolute, join, resolve } from 'node:path';
3
+ import { createTaskEntity } from './workflow/entity-creation.js';
4
+ /** A model node stays within its original Shortcut Job. Its durable child Task
5
+ * uses the existing Relay Worker adapter, lifecycle Graph and Troubleshooter.
6
+ * The parent Shortcut Graph, not the Worker Reconciler, selects DAG readiness. */
7
+ export async function runShortcutModelNode(options) {
8
+ const { store, reconciler, jobId, parentTaskId, node } = options;
9
+ if (!store.mutateJob)
10
+ throw new Error('Model nodes require the durable Relay SQLite store');
11
+ if (!/^[A-Za-z_][\w.-]*$/.test(node.id))
12
+ throw new Error('Invalid shortcut model node ID');
13
+ const taskId = `shortcut-${parentTaskId}-${node.id}`;
14
+ const initial = await store.load(jobId);
15
+ const parent = initial.tasks.find(t => t.id === parentTaskId);
16
+ if (!parent || parent.state !== 'RUNNING' || parent.executionId !== node.executionId || !parent.leaseOwner)
17
+ throw new Error('Model node parent execution is not leased by Shortcut Runner');
18
+ if (parent.output?.kind !== 'file' || !isAbsolute(parent.output.path))
19
+ throw new Error('Model nodes require a canonical absolute Task output directory');
20
+ const runRoot = dirname(parent.output.path);
21
+ const declaredRun = parent.input.match(/^- Canonical run:\s*(\/[^\r\n]+)$/m)?.[1]?.trim();
22
+ if (declaredRun && resolve(declaredRun) !== resolve(runRoot))
23
+ throw new Error('Shortcut Worker declared canonical run does not match the bound parent Task output directory');
24
+ const sourceRef = parent.input.match(/^- Private input evidence:\s*(\/[^\r\n]+)$/m)?.[1]?.trim();
25
+ if (sourceRef && (!declaredRun || dirname(resolve(sourceRef)) !== resolve(runRoot)))
26
+ throw new Error('Shortcut Worker source evidence is not confined to the declared canonical run');
27
+ const outputPath = join(runRoot, '.shortcut-node-results', `${taskId}.json`);
28
+ const started = initial.shortcutExecutionStartedAt && Date.parse(initial.shortcutExecutionStartedAt);
29
+ if (!started || !Number.isFinite(started))
30
+ throw new Error('Model node has no immutable Shortcut deadline origin');
31
+ const deadline = started + 20 * 60_000;
32
+ if (initial.shortcutExecutionDeadlineAt && Date.parse(initial.shortcutExecutionDeadlineAt) !== deadline)
33
+ throw new Error('Model node deadline differs from the original execution budget');
34
+ if (Date.now() >= deadline)
35
+ throw new Error('Shortcut execution budget exceeded before model node dispatch');
36
+ await mkdir(dirname(outputPath), { recursive: true, mode: 0o700 });
37
+ await store.mutateJob(jobId, current => {
38
+ const active = current.tasks.find(t => t.id === parentTaskId);
39
+ if (current.state !== 'ACTIVE' || current.executionMode !== 'shortcut' || current.contentOnly !== true || current.pause ||
40
+ !active || active.executionId !== node.executionId || active.state !== 'RUNNING' || !active.leaseOwner)
41
+ throw new Error('Shortcut model worker claim invalidated by Job lifecycle');
42
+ const cp = active.result?.data?.shortcut;
43
+ if (!cp || typeof cp !== 'object')
44
+ throw new Error('Shortcut model worker requires a persisted Graph checkpoint');
45
+ const state = cp;
46
+ if (state.nodes?.[node.id] || state.inFlight?.[node.id] !== node.executionId)
47
+ throw new Error('Model node is no longer pending in the current Graph execution');
48
+ state.workerNodes ??= {};
49
+ if (state.workerNodes[node.id] && state.workerNodes[node.id] !== taskId)
50
+ throw new Error('Conflicting durable Worker node mapping');
51
+ state.workerNodes[node.id] = taskId;
52
+ const existing = current.tasks.find(t => t.id === taskId);
53
+ if (existing) {
54
+ if (existing.parentTaskId !== parentTaskId || existing.agentName !== node.agent || existing.output?.kind !== 'file' || existing.output.path !== outputPath)
55
+ throw new Error('Durable Worker node identity mismatch');
56
+ }
57
+ else {
58
+ const now = new Date().toISOString();
59
+ const body = JSON.stringify({
60
+ source: 'shortcut-graph-node', jobId, parentTaskId, nodeId: node.id, agent: node.agent,
61
+ predecessorOutputs: node.predecessorOutputs,
62
+ originalInput: active.input,
63
+ ...(declaredRun ? { canonicalRunPath: declaredRun } : {}),
64
+ ...(sourceRef ? { sourceEvidencePath: sourceRef } : {}),
65
+ requiredResult: { status: 'COMPLETED', output: {}, artifacts: [] },
66
+ outputPath,
67
+ instruction: 'Execute only this Agent role for this DAG node. The ONLY structured DAG predecessor values are predecessorOutputs; never infer an undeclared sibling dependency. If canonicalRunPath is declared, read the authorized original source manifest and prior stage artifact files there as required by the project Agent/Stage contract; inspect and validate their real contents, source provenance, hashes and use rights. These files are allowed canonical run evidence, not an alternative DAG predecessor result and not proof of human approval. Do not claim they are absent merely because they are not repeated in predecessorOutputs. Write {status:"COMPLETED",output:{...},artifacts:[]} to outputPath only after meeting stage acceptance and send a correlated task.completed event. If a real prerequisite is unavailable, report the specific verified blocker and task.failed; do not fabricate, publish, approve or infer new permissions.'
68
+ });
69
+ current.tasks.push(createTaskEntity(current, {
70
+ jobId, id: taskId, title: `Shortcut model node ${node.id}`, kind: 'work', parentTaskId,
71
+ agentName: node.agent, dependencies: [], capabilities: ['model'], workerRequirements: { capabilities: ['model'] },
72
+ adapter: 'codex', input: body, output: { kind: 'file', path: outputPath },
73
+ attempt: 0, maxAttempts: 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null,
74
+ result: null, error: null, timeoutMs: Math.max(1, deadline - Date.now()), createdAt: now, updatedAt: now,
75
+ }));
76
+ }
77
+ return current;
78
+ });
79
+ while (true) {
80
+ if (node.signal.aborted)
81
+ throw node.signal.reason ?? new Error('Shortcut Worker node interrupted');
82
+ if (Date.now() >= deadline)
83
+ throw new Error('Shortcut execution budget exceeded while waiting for model node');
84
+ const current = await store.load(jobId);
85
+ if (current.state !== 'ACTIVE' || current.pause)
86
+ throw new Error('Shortcut Job cancelled/paused while Worker node was pending');
87
+ const task = current.tasks.find(t => t.id === taskId);
88
+ if (!task)
89
+ throw new Error('Worker node disappeared from the durable Job');
90
+ if (task.state === 'SUCCEEDED') {
91
+ const buffer = await readFile(outputPath);
92
+ const value = JSON.parse(buffer.toString('utf8'));
93
+ if (!value || typeof value !== 'object' || Array.isArray(value))
94
+ throw new Error('Worker Task reported success without contract-valid node output');
95
+ const record = value;
96
+ if (record.status !== 'COMPLETED' || !record.output || typeof record.output !== 'object' || Array.isArray(record.output))
97
+ throw new Error('Worker Task reported success without contract-valid node output');
98
+ // Some existing Worker roles report artifact records as {path,type}.
99
+ // Convert ONLY exact file records to the Shortcut contract's path list;
100
+ // the Graph executor still verifies realpath containment and SHA-256.
101
+ if (Array.isArray(record.artifacts)) {
102
+ const files = record.artifacts.map((item) => {
103
+ if (typeof item === 'string' && item.trim())
104
+ return item;
105
+ if (item && typeof item === 'object' && !Array.isArray(item)) {
106
+ const ref = item;
107
+ const fields = Object.keys(ref);
108
+ if (fields.length === 2 && fields.includes('path')
109
+ && ((fields.includes('type') && ref.type === 'file') || (fields.includes('kind') && ref.kind === 'file'))
110
+ && typeof ref.path === 'string' && ref.path.trim())
111
+ return ref.path;
112
+ }
113
+ throw new Error('Worker node returned unsupported artifact entry; expected a file path, {type:"file",path} or {kind:"file",path}');
114
+ });
115
+ return { ...record, artifacts: files };
116
+ }
117
+ if (!record.artifacts || typeof record.artifacts !== 'object')
118
+ throw new Error('Worker Task reported success without contract-valid artifact output');
119
+ return record;
120
+ }
121
+ if (task.state === 'CANCELLED')
122
+ throw new Error('Worker node cancelled');
123
+ if (task.state === 'BLOCKED')
124
+ throw new Error(`Worker node requires escalation: ${task.failureReason ?? task.error ?? task.id}`);
125
+ await reconciler.reconcile(jobId);
126
+ await new Promise(resolve => setTimeout(resolve, 100));
127
+ }
128
+ }
@@ -0,0 +1,50 @@
1
+ /** Optional project-declared Stage completion gate. Runs after any code/model
2
+ * node reports COMPLETED and before the canonical DAG accepts its result. */
3
+ import { readFile, realpath } from 'node:fs/promises';
4
+ import { resolve, relative, isAbsolute, sep, join } from 'node:path';
5
+ const within = (root, target) => { const rel = relative(root, target); return rel === '' || (rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel)); };
6
+ export async function validateShortcutStageGate(options) {
7
+ const root = await realpath(options.projectPath);
8
+ let manifest;
9
+ try {
10
+ manifest = JSON.parse(await readFile(join(root, 'project.run.json'), 'utf8'));
11
+ }
12
+ catch (error) {
13
+ if (error.code === 'ENOENT')
14
+ return;
15
+ throw error;
16
+ }
17
+ const config = manifest?.stageValidation;
18
+ if (!config || typeof config !== 'object' || Array.isArray(config))
19
+ return;
20
+ const declaration = config;
21
+ if (!declaration.agents || typeof declaration.agents !== 'object' || Array.isArray(declaration.agents))
22
+ throw new Error('Invalid Stage validator agent mapping');
23
+ const stage = declaration.agents[options.agent];
24
+ if (stage === undefined)
25
+ return;
26
+ if (typeof stage !== 'string' || !/^[-a-z]+$/.test(stage))
27
+ throw new Error('Invalid declared Stage ID');
28
+ const script = declaration.script;
29
+ if (typeof script !== 'string' || !/^scripts\/[a-zA-Z0-9._-]+\.mjs$/.test(script))
30
+ throw new Error('Invalid Stage validator script');
31
+ const file = await realpath(resolve(root, script));
32
+ if (!within(root, file))
33
+ throw new Error('Stage validator escaped project root');
34
+ const run = await realpath(options.runPath);
35
+ if (!within(await realpath(resolve(root, 'runs')), run) || run === root)
36
+ throw new Error('Stage validator run escaped project runs');
37
+ const response = await options.execute([process.execPath, file, stage, run], root);
38
+ let outcome;
39
+ try {
40
+ outcome = JSON.parse(response.stdout);
41
+ }
42
+ catch {
43
+ throw new Error('Stage validator did not return a structured contract result');
44
+ }
45
+ const report = outcome;
46
+ if (response.code !== 0 || report.stage !== stage || report.status !== 'PASS' || (Array.isArray(report.errors) && report.errors.length > 0)) {
47
+ const detail = Array.isArray(report.errors) ? JSON.stringify(report.errors).slice(0, 1200) : response.stderr.slice(0, 1200);
48
+ throw new Error('STAGE_CONTRACT_FAILED ' + stage + ': ' + detail);
49
+ }
50
+ }
@@ -0,0 +1,73 @@
1
+ import { dispatchJobLifecycleSync } from './workflow/lifecycle.js';
2
+ /** One foreground owner drives all Worker fallback and Troubleshooter Tasks.
3
+ * No background scheduler may mutate a Shortcut Job. */
4
+ export async function driveShortcutWorkers(options) {
5
+ const { store, jobId, reconciler, taskId } = options;
6
+ if (!store.mutateJob)
7
+ throw new Error('Foreground Worker fallback requires atomic Relay SQLite');
8
+ const initial = await store.mutateJob(jobId, job => {
9
+ if (job.executionMode !== 'shortcut' || job.contentOnly !== true || job.state !== 'ACTIVE')
10
+ throw new Error('Not an active Shortcut Job');
11
+ if (!job.tasks.find(task => task.id === taskId))
12
+ throw new Error('Shortcut parent Task missing');
13
+ const now = Date.now();
14
+ if (!job.shortcutExecutionStartedAt)
15
+ job.shortcutExecutionStartedAt = new Date(now).toISOString();
16
+ const first = Date.parse(job.shortcutExecutionStartedAt);
17
+ if (!Number.isFinite(first))
18
+ throw new Error('Invalid original Shortcut start time');
19
+ const deadline = new Date(first + 20 * 60_000).toISOString();
20
+ if (job.shortcutExecutionDeadlineAt && job.shortcutExecutionDeadlineAt !== deadline)
21
+ throw new Error('Shortcut deadline changed');
22
+ job.shortcutExecutionDeadlineAt = deadline;
23
+ return job;
24
+ });
25
+ const deadline = Date.parse(initial.shortcutExecutionDeadlineAt);
26
+ const last = new Map();
27
+ const stopWatching = await reconciler.watch(jobId);
28
+ const observe = (job) => {
29
+ for (const task of job.tasks) {
30
+ const key = `${task.state}:${task.attempt}:${task.error ?? ''}`;
31
+ if (last.get(task.id) !== key) {
32
+ last.set(task.id, key);
33
+ options.onTask?.(task);
34
+ }
35
+ }
36
+ };
37
+ try {
38
+ while (true) {
39
+ if (options.signal?.aborted)
40
+ return { status: 'INTERRUPTED', job: await store.load(jobId) };
41
+ if (Date.now() >= deadline)
42
+ return { status: 'TIMED_OUT', job: await store.load(jobId) };
43
+ await reconciler.reconcile(jobId);
44
+ let job = await store.load(jobId);
45
+ observe(job);
46
+ if (job.state === 'COMPLETED')
47
+ return { status: 'COMPLETED', job };
48
+ if (job.state === 'CANCELLED')
49
+ return { status: 'FAILED', job };
50
+ if (job.tasks.every(task => task.state === 'SUCCEEDED')) {
51
+ job = await store.mutateJob(jobId, current => {
52
+ if (current.state !== 'ACTIVE' || !current.tasks.length || !current.tasks.every(task => task.state === 'SUCCEEDED')
53
+ || current.prNumber !== 0 || current.localMerge || current.autoMerge !== false || current.reviewEnabled !== false || current.review || current.plans?.length)
54
+ throw new Error('Shortcut completion requires all durable Tasks and content-only policy');
55
+ const decision = dispatchJobLifecycleSync(current, 'shortcut.completed', { shortcutCompletionAllowed: true });
56
+ if (!decision.accepted || decision.target !== 'COMPLETED')
57
+ throw new Error('Job Graph rejected Shortcut completion');
58
+ return current;
59
+ });
60
+ return { status: 'COMPLETED', job };
61
+ }
62
+ if (job.tasks.some(task => task.state === 'BLOCKED'))
63
+ return { status: 'WAITING_EVENT', job };
64
+ if (job.tasks.some(task => task.agentName === 'troubleshooter' && task.state === 'FAILED' && task.attempt >= task.maxAttempts))
65
+ return { status: 'FAILED', job };
66
+ await new Promise(resolve => setTimeout(resolve, 350));
67
+ }
68
+ }
69
+ finally {
70
+ await stopWatching();
71
+ await reconciler.close();
72
+ }
73
+ }