agents-relay 1.0.177 → 2.0.1

package/dist/troubleshooter.js

@@ -1,4 +1,6 @@
 import { taskOverallTimeoutMs } from './types.js';
+import { dispatchTroubleshooter } from './workflow/troubleshooter-v2.js';
+import { createTaskEntity } from './workflow/entity-creation.js';
 function slug(value) {
     return value.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 72) || 'task';
 }
@@ -46,15 +48,20 @@ export function pendingTroubleshooterTasks(job) {
     const existing = new Set(job.tasks.filter(task => task.agentName === 'troubleshooter').map(task => task.id));
     const recoveries = [];
     for (const task of job.tasks) {
-        if (!['FAILED', 'BLOCKED'].includes(task.state) || task.kind === 'planner' || task.agentName === 'troubleshooter' || !belongsToCurrentRun(job, task))
-            continue;
-        if (task.state === 'BLOCKED' && task.unblock)
-            continue;
         const id = troubleshooterTaskId(task);
-        if (existing.has(id) || hasRecoveryBarrier(job, task))
+        let create = false;
+        const decision = dispatchTroubleshooter({
+            failedOrBlocked: ['FAILED', 'BLOCKED'].includes(task.state),
+            ordinaryWork: task.kind !== 'planner' && task.agentName !== 'troubleshooter',
+            currentRun: belongsToCurrentRun(job, task),
+            needsRecovery: !(task.state === 'BLOCKED' && Boolean(task.unblock)),
+            idUnused: !existing.has(id),
+            noRecoveryBarrier: !hasRecoveryBarrier(job, task),
+        }, () => { create = true; });
+        if (!decision.accepted || !create)
             continue;
         const now = new Date().toISOString();
-        recoveries.push({
+        recoveries.push(createTaskEntity(job, {
             jobId: job.id,
             id,
             kind: 'work',
@@ -71,7 +78,6 @@ export function pendingTroubleshooterTasks(job) {
             output: { kind: 'task_pr' },
             continuation: null,
             continuationDeliveredAt: null,
-            state: 'QUEUED',
             attempt: 0,
             maxAttempts: 1,
             leaseOwner: null,
@@ -84,7 +90,7 @@ export function pendingTroubleshooterTasks(job) {
             timeoutMs: taskOverallTimeoutMs('M'),
             createdAt: now,
             updatedAt: now,
-        });
+        }));
     }
     return recoveries;
 }

package/dist/types.js

@@ -1,7 +1,7 @@
-import { jobLifecycleWorkflow, taskLifecycleWorkflow } from './workflow/definitions.js';
+import { assertV2StateTransition, jobLifecycleV2, taskLifecycleV2 } from './workflow/definitions-v2.js';
 export const STORY_SIZE_TIMEOUT_MS = { S: 300000, M: 900000, L: 2700000 };
 export function storySizeTimeoutMs(size) { return STORY_SIZE_TIMEOUT_MS[size]; }
 export function taskOverallTimeoutMs(size, reasoning) { return storySizeTimeoutMs(size) * (reasoning?.toLowerCase() === 'high' ? 2 : 1); }
 export function chatGptStartAckTimeoutMs(overallTimeoutMs) { return Math.min(600000, Math.max(120000, Math.floor(overallTimeoutMs / 3))); }
-export function assertJobLifecycleTransition(from, to) { jobLifecycleWorkflow.assertStateTransition(from, to, 'job'); }
-export function assertTaskTransition(from, to) { taskLifecycleWorkflow.assertStateTransition(from, to, 'task'); }
+export function assertJobLifecycleTransition(from, to) { assertV2StateTransition(jobLifecycleV2.graph, from, to, 'job'); }
+export function assertTaskTransition(from, to) { assertV2StateTransition(taskLifecycleV2.graph, from, to, 'task'); }

package/dist/unblock.js

@@ -1,4 +1,6 @@
-import { extendRetryBudget, transitionTaskEvent } from './scheduler.js';
+import { transitionTaskEvent } from './scheduler.js';
+import { applyTaskUnblockRetryAction } from './task-actions.js';
+import { dispatchAuthoritativeUnblock } from './workflow/authoritative-unblock-v2.js';
 export function isEffectivelyBlocked(task) { return task.kind !== 'planner' && task.state === 'BLOCKED'; }
 function baselineFor(task) {
     return task.blockedBaseline ?? { blockedAt: task.updatedAt, reason: task.error ?? undefined };
@@ -69,24 +71,32 @@ export async function unblockAutonomousTasks(options) {
 export async function unblockTask(options) {
     if (!isEffectivelyBlocked(options.task))
         throw new Error(`Task ${options.task.id} is not an effective BLOCKED work task`);
-    if (options.job.executionMode === 'autonomous')
-        return { replanning: true, planTrigger: await unblockAutonomousTasks({ store: options.store, job: options.job, tasks: [options.task], trigger: options.trigger, now: options.now }) };
-    const now = options.now ?? new Date().toISOString();
-    const currentHeadSha = await options.store.headSha?.() ?? options.job.headSha ?? null;
-    const baseline = baselineFor(options.task);
-    options.task.blockedBaseline = baseline;
-    const facts = unblockFacts(options.job, [options.task], currentHeadSha, options.trigger.reason);
-    options.task.unblock = { at: now, source: options.trigger.source, reason: options.trigger.reason, baseline, currentHeadSha: currentHeadSha ?? undefined, facts, blockerJobId: options.trigger.blockerJobId, resolution: options.trigger.resolution };
-    await transitionTaskEvent(options.task, 'task.unblocked');
-    await options.store.saveTask(options.task);
-    options.task.maxAttempts = extendRetryBudget(options.task);
-    await transitionTaskEvent(options.task, 'retry');
-    options.task.error = null;
-    options.task.leaseOwner = null;
-    options.task.leaseExpiresAt = null;
-    options.task.executionId = null;
-    options.task.updatedAt = now;
-    delete options.task.blockedBy;
-    await options.store.saveTask(options.task);
-    return { replanning: false };
+    let result;
+    const decision = await dispatchAuthoritativeUnblock(options.job.executionMode === 'autonomous', async (actionId) => {
+        if (actionId === 'unblock.replan') {
+            result = { replanning: true, planTrigger: await unblockAutonomousTasks({ store: options.store, job: options.job, tasks: [options.task], trigger: options.trigger, now: options.now }) };
+            return {};
+        }
+        if (actionId === 'unblock.retry') {
+            const now = options.now ?? new Date().toISOString();
+            const currentHeadSha = await options.store.headSha?.() ?? options.job.headSha ?? null;
+            const baseline = baselineFor(options.task);
+            options.task.blockedBaseline = baseline;
+            const facts = unblockFacts(options.job, [options.task], currentHeadSha, options.trigger.reason);
+            options.task.unblock = { at: now, source: options.trigger.source, reason: options.trigger.reason, baseline, currentHeadSha: currentHeadSha ?? undefined, facts, blockerJobId: options.trigger.blockerJobId, resolution: options.trigger.resolution };
+            await transitionTaskEvent(options.task, 'task.unblocked');
+            await options.store.saveTask(options.task);
+            await applyTaskUnblockRetryAction(options.task);
+            options.task.updatedAt = now;
+            await options.store.saveTask(options.task);
+            result = { replanning: false };
+            return {};
+        }
+        throw new Error('Unsupported authoritative unblock action ' + actionId);
+    });
+    if (!decision.accepted)
+        throw new Error('Authoritative unblock graph rejected task.authoritative_unblock');
+    if (!result)
+        throw new Error('Authoritative unblock graph completed without an action result');
+    return result;
 }

package/dist/workflow/authoritative-unblock-v2.js

@@ -0,0 +1,20 @@
+import { readFileSync } from 'node:fs';
+import { GraphRuntime } from './graph-v2.js';
+import { dispatchWorkflowGraph, dispatchWorkflowGraphSync } from './dispatcher.js';
+const source = readFileSync(new URL('../../workflow/authoritative-unblock-v2.mmd', import.meta.url), 'utf8');
+const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
+export const authoritativeUnblockV2 = new GraphRuntime(source, {
+    states: new Set(['blocked', 'autonomous_replan', 'fixed_retry']),
+    guards: { autonomousJob: boolGuard('autonomousJob') },
+    actions: {
+        'unblock.replan': { id: 'unblock.replan' },
+        'unblock.retry': { id: 'unblock.retry' },
+    },
+    events: { 'task.authoritative_unblock': { id: 'task.authoritative_unblock' } },
+});
+export async function dispatchAuthoritativeUnblock(autonomousJob, executeAction) {
+    return dispatchWorkflowGraph(authoritativeUnblockV2, { initialState: 'blocked', input: { transport: 'event', id: 'task.authoritative_unblock', payload: {} }, durableFacts: { autonomousJob }, executeAction });
+}
+export function decideAuthoritativeUnblock(autonomousJob) {
+    return dispatchWorkflowGraphSync(authoritativeUnblockV2, { initialState: 'blocked', input: { transport: 'event', id: 'task.authoritative_unblock', payload: {} }, durableFacts: { autonomousJob } });
+}

package/dist/workflow/blocker-resolution-v2.js

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+import { GraphRuntime } from './graph-v2.js';
+import { dispatchWorkflowGraph, dispatchWorkflowGraphSync } from './dispatcher.js';
+const source = readFileSync(new URL('../../workflow/blocker-resolution-v2.mmd', import.meta.url), 'utf8');
+const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
+export const blockerResolutionV2 = new GraphRuntime(source, {
+    states: new Set([
+        'waiting', 'check_target', 'check_autonomous', 'check_effective', 'check_already_unblocked',
+        'check_draft', 'check_blocked', 'check_failed', 'check_unblocked', 'wait', 'obsolete', 'resumed',
+    ]),
+    guards: {
+        resolutionAllowed: boolGuard('resolutionAllowed'),
+        targetMatches: boolGuard('targetMatches'),
+        autonomousJob: boolGuard('autonomousJob'),
+        effectivelyBlocked: boolGuard('effectivelyBlocked'),
+        alreadyUnblocked: boolGuard('alreadyUnblocked'),
+        isDraft: boolGuard('isDraft'),
+        isBlocked: boolGuard('isBlocked'),
+        isFailed: boolGuard('isFailed'),
+        isUnblocked: boolGuard('isUnblocked'),
+    },
+    actions: Object.fromEntries([
+        'blocker.autonomousUnblock', 'blocker.acceptExistingUnblock', 'blocker.releaseDraft',
+        'blocker.unblockTask', 'blocker.retryFailed', 'blocker.retryUnblocked',
+    ].map(id => [id, { id }])),
+    events: { 'blocker.resolved': { id: 'blocker.resolved' } },
+});
+export async function dispatchBlockerResolution(facts, executeAction) {
+    return dispatchWorkflowGraph(blockerResolutionV2, { initialState: 'waiting', input: { transport: 'event', id: 'blocker.resolved', payload: {} }, durableFacts: facts, isTransientState: state => state.startsWith('check_'), maxSteps: 10, executeAction });
+}
+export function decideBlockerResolution(facts) {
+    return dispatchWorkflowGraphSync(blockerResolutionV2, { initialState: 'waiting', input: { transport: 'event', id: 'blocker.resolved', payload: {} }, durableFacts: facts, isTransientState: state => state.startsWith('check_'), maxSteps: 10 });
+}

package/dist/workflow/contracts.js

@@ -6,11 +6,17 @@ export const WORKFLOW_EVENT_NAMES = [
     'effect.cancelActiveTasks.failed',
     'effect.launchTask.failed',
     'effect.mergePullRequest.failed',
+    'execution.orphaned',
     'fail',
     'hold',
+    'lease.expired',
     'implementation.completed',
     'pr.closed',
     'pr.merged',
+    'queue',
+    'plan.requested',
+    'planner.failed',
+    'planner.unavailable',
     'reconcile',
     'release',
     'retry',
@@ -36,10 +42,25 @@ export const WORKFLOW_FACT_NAMES = [
     'notMerged',
     'autoMerge',
     'recoverableExecution',
+    'retryAvailable',
+    'initialPlan',
+    'scheduledRun',
+    'hasUnblock',
+    'manualPlan',
+    'prOpen',
+    'reviewDisabled',
+    'implementationComplete',
+    'headAvailable',
+    'mergeCapable',
 ];
 export const WORKFLOW_MUTATION_NAMES = [
     'mutation.clearError',
     'mutation.clearFailureReason',
+    'mutation.clearLease',
+    'mutation.clearExecution',
+    'mutation.markLeaseExpired',
+    'mutation.markStartupOrphanedExhausted',
+    'mutation.markPlannerUnavailable',
 ];
 export const WORKFLOW_EFFECT_NAMES = [
     'effect.launchTask',

package/dist/workflow/definitions-v2.js

@@ -0,0 +1,75 @@
+import { readFileSync } from 'node:fs';
+import { GraphRuntime } from './graph-v2.js';
+import { WORKFLOW_EFFECT_NAMES, WORKFLOW_EVENT_NAMES, WORKFLOW_MUTATION_NAMES, } from './contracts.js';
+const TASK_STATES = ['DRAFT', 'QUEUED', 'RUNNING', 'BLOCKED', 'UNBLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED'];
+const JOB_STATES = ['DRAFT', 'ACTIVE', 'COMPLETED', 'CANCELLED'];
+const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
+function eventRegistry() {
+    return Object.fromEntries(WORKFLOW_EVENT_NAMES.map(id => [id, { id }]));
+}
+function actionRegistry() {
+    return Object.fromEntries([...WORKFLOW_MUTATION_NAMES, ...WORKFLOW_EFFECT_NAMES].map(id => [id, { id }]));
+}
+function load(name, states, guards) {
+    const url = new URL(`../../workflow/${name}-v2.mmd`, import.meta.url);
+    return new GraphRuntime(readFileSync(url, 'utf8'), {
+        states: new Set(states),
+        guards,
+        actions: actionRegistry(),
+        events: eventRegistry(),
+    });
+}
+export const taskLifecycleV2 = load('task-lifecycle', TASK_STATES, {
+    dependenciesSatisfied: boolGuard('dependenciesSatisfied'),
+    dependenciesUnsatisfied: boolGuard('dependenciesUnsatisfied'),
+    runnable: boolGuard('runnable'),
+    dispatchable: boolGuard('dispatchable'),
+    recoverableExecution: boolGuard('recoverableExecution'),
+    retryAvailable: boolGuard('retryAvailable'),
+});
+export const jobLifecycleV2 = load('job-lifecycle', JOB_STATES, {
+    notMerged: boolGuard('notMerged'),
+    autoMerge: boolGuard('autoMerge'),
+    prOpen: boolGuard('prOpen'),
+    reviewDisabled: boolGuard('reviewDisabled'),
+    implementationComplete: boolGuard('implementationComplete'),
+    headAvailable: boolGuard('headAvailable'),
+    mergeCapable: boolGuard('mergeCapable'),
+});
+function topologyTargets(graph, from) {
+    const source = [...graph.nodes.values()].find(node => node.kind === 'state' && node.semanticId === from);
+    if (!source)
+        throw new Error(`Unknown workflow state ${from}`);
+    const targets = new Set();
+    const visit = (nodeId, seen) => {
+        if (seen.has(nodeId))
+            return;
+        seen.add(nodeId);
+        const node = graph.nodes.get(nodeId);
+        if (!node)
+            return;
+        if (node.kind === 'state') {
+            targets.add(node.semanticId);
+            return;
+        }
+        for (const edge of graph.edges) {
+            if (edge.from === nodeId && edge.kind !== 'emit')
+                visit(edge.to, new Set(seen));
+        }
+    };
+    for (const edge of graph.edges) {
+        if (edge.from === source.id && (edge.kind === 'on' || edge.kind === 'request')) {
+            visit(edge.to, new Set([source.id]));
+        }
+    }
+    return targets;
+}
+export function assertV2StateTransition(graph, from, to, kind) {
+    if (from === to)
+        return;
+    const states = new Set([...graph.nodes.values()].filter(node => node.kind === 'state').map(node => node.semanticId));
+    if (!states.has(from) || !states.has(to))
+        throw new Error(`Unknown ${kind} state ${!states.has(from) ? from : to}`);
+    if (!topologyTargets(graph, from).has(to))
+        throw new Error(`Invalid ${kind} transition ${from} -> ${to}`);
+}

package/dist/workflow/dispatcher.js

@@ -0,0 +1,56 @@
+import { GraphDispatcher } from './graph-v2.js';
+/**
+ * The single production graph execution boundary.
+ * Ingress adapters normalize input/facts, while GraphDispatcher alone evaluates,
+ * persists graph transitions, executes graph-selected actions, and emits events.
+ */
+export async function dispatchWorkflowGraph(runtime, options) {
+    let current = options.initialState;
+    const maxSteps = options.maxSteps ?? 1;
+    for (let step = 0; step < maxSteps; step += 1) {
+        const dispatcher = new GraphDispatcher(runtime, {
+            persistTransition: async (transition) => { await options.persistTransition?.(transition.source, transition.target); },
+            executeAction: options.executeAction ? async (actionId) => await options.executeAction(actionId) : undefined,
+            publishEvent: async (event) => { await options.publishEvent?.(event.id, event.payload); },
+        });
+        const result = await dispatcher.dispatch({
+            currentState: current,
+            input: options.input,
+            durableFacts: options.durableFacts ?? {},
+        });
+        if (!result.decision.accepted)
+            return result.decision;
+        current = result.decision.target;
+        if (!options.isTransientState?.(current))
+            return result.decision;
+    }
+    return { accepted: false, source: current, reason: 'no_transition' };
+}
+export function dispatchWorkflowGraphSync(runtime, options) {
+    let current = options.initialState;
+    const maxSteps = options.maxSteps ?? 1;
+    for (let step = 0; step < maxSteps; step += 1) {
+        const dispatcher = new GraphDispatcher(runtime, {
+            persistTransition: transition => { const result = options.persistTransition?.(transition.source, transition.target); if (result instanceof Promise)
+                throw new Error('sync workflow persistTransition returned Promise'); },
+            executeAction: options.executeAction ? actionId => { const result = options.executeAction(actionId); if (result instanceof Promise)
+                throw new Error('sync workflow executeAction returned Promise'); return result; } : undefined,
+            publishEvent: event => { const result = options.publishEvent?.(event.id, event.payload); if (result instanceof Promise)
+                throw new Error('sync workflow publishEvent returned Promise'); },
+        });
+        const result = dispatcher.dispatchSync({ currentState: current, input: options.input, durableFacts: options.durableFacts ?? {} });
+        if (!result.decision.accepted)
+            return result.decision;
+        current = result.decision.target;
+        if (!options.isTransientState?.(current))
+            return result.decision;
+    }
+    return { accepted: false, source: current, reason: 'no_transition' };
+}
+export async function dispatchWorkflowTargetOverride(runtime, options) {
+    // Administrative correction still derives legality from the canonical Mermaid graph.
+    // It intentionally executes no workflow actions/effects: this is a state repair, not an event replay.
+    const { assertV2StateTransition } = await import('./definitions-v2.js');
+    assertV2StateTransition(runtime.graph, options.currentState, options.targetState, options.kind);
+    await options.persistTransition(options.currentState, options.targetState);
+}

package/dist/workflow/entity-creation.js

@@ -0,0 +1,32 @@
+import { dispatchJobLifecycleSync, dispatchTaskLifecycleSync } from './lifecycle.js';
+function dependenciesSatisfied(job, dependencies) {
+    if (dependencies.length === 0)
+        return true;
+    const byId = new Map(job.tasks.map(task => [task.id, task]));
+    return dependencies.every(id => byId.get(id)?.state === 'SUCCEEDED');
+}
+/**
+ * Canonical creation boundary for new Task entities.
+ * Constructors provide metadata/facts only; the Task lifecycle graph derives
+ * whether a fresh Task remains DRAFT or becomes QUEUED.
+ */
+export function createTaskEntity(job, value, options = {}) {
+    const task = { ...value, state: 'DRAFT' };
+    if (!options.defer) {
+        dispatchTaskLifecycleSync(task, 'reconcile', {
+            dependenciesSatisfied: dependenciesSatisfied(job, task.dependencies),
+        });
+    }
+    return task;
+}
+/**
+ * Canonical creation boundary for new Job entities.
+ * New Jobs begin at the graph initial state and scheduled creation is expressed
+ * as the normal activate lifecycle event.
+ */
+export function createJobEntity(value, options = {}) {
+    const job = { ...value, state: 'DRAFT' };
+    if (options.activate)
+        dispatchJobLifecycleSync(job, 'activate');
+    return job;
+}