agents-relay 1.0.89 → 1.0.91

package/dist/workflow/definitions.js

@@ -1,14 +1,28 @@
 import { readFileSync } from 'node:fs';
 import { parseExecutableMermaid, WorkflowEngine } from './mermaid.js';
-function load(name, guards = {}, actions = {}) {
+import { WORKFLOW_EFFECT_NAMES, WORKFLOW_EVENT_NAMES, WORKFLOW_MUTATION_NAMES } from './contracts.js';
+function declarativeActions() {
+    return Object.fromEntries([...WORKFLOW_MUTATION_NAMES, ...WORKFLOW_EFFECT_NAMES].map(name => [name, { declarative: true }]));
+}
+function load(name, guards = {}) {
     const url = new URL(`../../workflow/${name}.mmd`, import.meta.url);
-    return new WorkflowEngine(parseExecutableMermaid(readFileSync(url, 'utf8')), guards, actions);
+    const graph = parseExecutableMermaid(readFileSync(url, 'utf8'));
+    const canonicalEvents = new Set(WORKFLOW_EVENT_NAMES);
+    for (const transition of graph.transitions) {
+        if (!canonicalEvents.has(transition.event)) {
+            throw new Error(`Unknown canonical workflow event ${transition.event} referenced at line ${transition.line}`);
+        }
+    }
+    return new WorkflowEngine(graph, guards, declarativeActions());
 }
 const booleanGuard = (name) => context => context[name] === true;
-const lifecycleAction = () => { };
-export const jobLifecycleWorkflow = load('job-lifecycle', { notMerged: booleanGuard('notMerged') }, { cancelJob: lifecycleAction });
+export const jobLifecycleWorkflow = load('job-lifecycle', {
+    notMerged: booleanGuard('notMerged'),
+    autoMerge: booleanGuard('autoMerge'),
+});
 export const taskLifecycleWorkflow = load('task-lifecycle', {
     dependenciesSatisfied: booleanGuard('dependenciesSatisfied'),
     dependenciesUnsatisfied: booleanGuard('dependenciesUnsatisfied'),
     runnable: booleanGuard('runnable'),
-}, { release: lifecycleAction, hold: lifecycleAction });
+    dispatchable: booleanGuard('dispatchable'),
+});

package/dist/workflow/effects.js

@@ -0,0 +1,74 @@
+export class MemoryWorkflowEffectReceiptStore {
+    completed = new Set();
+    async has(key) { return this.completed.has(key); }
+    async markCompleted(key) { this.completed.add(key); }
+}
+export class WorkflowEffectHandler {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+    idempotencyKey(context) {
+        return `${this.name}:${context.jobId}:${context.taskId ?? 'job'}:${context.transitionKey}`;
+    }
+}
+export class CallbackWorkflowEffectHandler extends WorkflowEffectHandler {
+    callback;
+    key;
+    constructor(name, callback, key) {
+        super(name);
+        this.callback = callback;
+        this.key = key;
+    }
+    idempotencyKey(context) {
+        return this.key?.(context) ?? super.idempotencyKey(context);
+    }
+    async execute(context) { await this.callback(context); }
+}
+export class WorkflowEffectExecutor {
+    receipts;
+    handlers = new Map();
+    constructor(handlers = [], receipts = new MemoryWorkflowEffectReceiptStore()) {
+        this.receipts = receipts;
+        for (const handler of handlers)
+            this.register(handler);
+    }
+    register(handler) {
+        if (this.handlers.has(handler.name))
+            throw new Error(`Workflow effect handler already registered: ${handler.name}`);
+        this.handlers.set(handler.name, handler);
+    }
+    async execute(effects, context, onOutcome) {
+        const outcomes = [];
+        for (const effect of effects) {
+            const handler = this.handlers.get(effect);
+            if (!handler)
+                throw new Error(`No workflow effect handler registered for ${effect}`);
+            const key = handler.idempotencyKey(context);
+            if (await this.receipts.has(key)) {
+                const outcome = { effect, key, status: 'deduplicated' };
+                outcomes.push(outcome);
+                await onOutcome?.(outcome);
+                continue;
+            }
+            try {
+                await handler.execute(context);
+                await this.receipts.markCompleted(key);
+                const outcome = { effect, key, status: 'completed' };
+                outcomes.push(outcome);
+                await onOutcome?.(outcome);
+            }
+            catch (error) {
+                const outcome = {
+                    effect,
+                    key,
+                    status: 'failed',
+                    error: error instanceof Error ? error.message : String(error),
+                };
+                outcomes.push(outcome);
+                await onOutcome?.(outcome);
+            }
+        }
+        return outcomes;
+    }
+}

package/dist/workflow/mermaid.js

@@ -144,7 +144,10 @@ export class WorkflowEngine {
             throw new Error(`Ambiguous workflow transition from ${state} on ${event}`);
         const transition = enabled[0];
         for (const actionName of transition.actions) {
-            const value = this.actions[actionName](context, transition);
+            const action = this.actions[actionName];
+            if (typeof action !== 'function')
+                continue;
+            const value = action(context, transition);
             if (value instanceof Promise)
                 throw new Error(`Workflow action ${actionName} is asynchronous and cannot be used in a synchronous transition`);
         }
@@ -173,7 +176,8 @@ export class WorkflowEngine {
         const transition = enabled[0];
         for (const actionName of transition.actions) {
             const action = this.actions[actionName];
-            await action(context, transition);
+            if (typeof action === 'function')
+                await action(context, transition);
         }
         return transition.to;
     }

package/dist/workflow/rollout.js

@@ -1,4 +1,6 @@
 import { jobLifecycleWorkflow, taskLifecycleWorkflow } from './definitions.js';
+import { classifyWorkflowActions, emptyWorkflowDecision, } from './contracts.js';
+import { graphWorkflowDecision } from './runtime.js';
 let modeOverride = null;
 let reporter = null;
 let matches = 0;
@@ -13,108 +15,116 @@ export function parseWorkflowRolloutMode(value) {
 export function workflowRolloutMode() {
     return modeOverride ?? parseWorkflowRolloutMode(process.env.AGENTS_RELAY_WORKFLOW_MODE);
 }
-export function setWorkflowRolloutMode(mode) {
-    modeOverride = mode;
-}
-export function setWorkflowShadowReporter(value) {
-    reporter = value;
-}
-export function resetWorkflowRolloutDiagnostics() {
-    matches = 0;
-    mismatches = 0;
-}
+export function setWorkflowRolloutMode(mode) { modeOverride = mode; }
+export function setWorkflowShadowReporter(value) { reporter = value; }
+export function resetWorkflowRolloutDiagnostics() { matches = 0; mismatches = 0; }
 export function workflowRolloutSnapshot() {
     return { mode: workflowRolloutMode(), matches, mismatches };
 }
-function graphDecision(engine, from, event, context) {
-    const enabled = engine.enabledSync(from, event, context);
-    if (enabled.length === 0)
-        return { accepted: false, target: null, guard: null, actions: [], reason: 'no_transition' };
-    if (enabled.length > 1)
-        return { accepted: false, target: null, guard: null, actions: [], reason: 'ambiguous' };
-    const transition = enabled[0];
+function accepted(target, guard = null, actions = []) {
+    const actionList = [...actions];
     return {
         accepted: true,
-        target: transition.to,
-        guard: transition.guard,
-        actions: [...transition.actions],
+        target,
+        guard,
+        actions: actionList,
+        ...classifyWorkflowActions(actionList),
         reason: 'accepted',
     };
 }
+const CLEAR = ['mutation.clearError', 'mutation.clearFailureReason'];
 const taskLegacy = {
     DRAFT: {
-        release: { target: 'QUEUED' },
+        release: { target: 'QUEUED', actions: CLEAR },
         block: { target: 'BLOCKED' },
         cancel: { target: 'CANCELLED' },
     },
     QUEUED: {
         hold: { target: 'DRAFT' },
-        'task.started': { target: 'RUNNING' },
+        'task.started': { target: 'RUNNING', actions: CLEAR },
         block: { target: 'BLOCKED' },
         fail: { target: 'FAILED' },
+        'effect.launchTask.failed': { target: 'FAILED' },
         cancel: { target: 'CANCELLED' },
     },
     RUNNING: {
         'task.blocked': { target: 'BLOCKED' },
-        'task.completed': { target: 'SUCCEEDED' },
+        'task.completed': { target: 'SUCCEEDED', actions: CLEAR },
         'task.failed': { target: 'FAILED' },
         'task.cancelled': { target: 'CANCELLED' },
     },
     BLOCKED: {
-        retry: { target: 'QUEUED' },
+        retry: { target: 'QUEUED', actions: CLEAR },
         cancel: { target: 'CANCELLED' },
     },
     SUCCEEDED: {},
     FAILED: {
-        retry: { target: 'QUEUED' },
-        'reconcile.started': { target: 'RUNNING' },
-        'reconcile.completed': { target: 'SUCCEEDED' },
+        retry: { target: 'QUEUED', actions: CLEAR },
+        'reconcile.started': { target: 'RUNNING', actions: CLEAR },
+        'reconcile.completed': { target: 'SUCCEEDED', actions: CLEAR },
         'reconcile.blocked': { target: 'BLOCKED' },
         cancel: { target: 'CANCELLED' },
     },
     CANCELLED: {},
 };
+const CANCEL_EFFECT = ['effect.cancelActiveTasks'];
+const MERGE_EFFECT = ['effect.mergePullRequest'];
 const jobLegacy = {
     DRAFT: {
         activate: { target: 'ACTIVE' },
-        'pr.merged': { target: 'COMPLETED' },
+        'pr.merged': { target: 'COMPLETED', actions: CANCEL_EFFECT },
         cancel: { target: 'CANCELLED' },
     },
     ACTIVE: {
-        'pr.merged': { target: 'COMPLETED' },
+        'pr.merged': { target: 'COMPLETED', actions: CANCEL_EFFECT },
         cancel: { target: 'CANCELLED' },
     },
-    COMPLETED: {},
+    COMPLETED: {
+        'effect.cancelActiveTasks.failed': { target: 'COMPLETED' },
+    },
     CANCELLED: {
-        'pr.merged': { target: 'COMPLETED' },
+        'pr.merged': { target: 'COMPLETED', actions: CANCEL_EFFECT },
+        'effect.cancelActiveTasks.failed': { target: 'CANCELLED' },
     },
 };
-function taskLegacyDecision(from, event, context) {
+function taskLegacyDecision(from, event, facts) {
     if (event === 'reconcile') {
-        if (from === 'DRAFT' && context.dependenciesSatisfied === true)
-            return { accepted: true, target: 'QUEUED', guard: 'dependenciesSatisfied', actions: ['release'], reason: 'accepted' };
-        if (from === 'QUEUED' && context.dependenciesUnsatisfied === true)
-            return { accepted: true, target: 'DRAFT', guard: 'dependenciesUnsatisfied', actions: ['hold'], reason: 'accepted' };
-        if (from === 'QUEUED' && context.runnable === true)
-            return { accepted: true, target: 'QUEUED', guard: 'runnable', actions: ['release'], reason: 'accepted' };
-        return { accepted: false, target: null, guard: null, actions: [], reason: 'no_transition' };
+        if (from === 'DRAFT' && facts.dependenciesSatisfied === true)
+            return accepted('QUEUED', 'dependenciesSatisfied', CLEAR);
+        if (from === 'QUEUED' && facts.dependenciesUnsatisfied === true)
+            return accepted('DRAFT', 'dependenciesUnsatisfied');
+        if (from === 'QUEUED' && facts.runnable === true)
+            return accepted('QUEUED', 'runnable', CLEAR);
+        return emptyWorkflowDecision('no_transition');
+    }
+    if (event === 'dispatch') {
+        if (from === 'QUEUED' && facts.dispatchable === true)
+            return accepted('QUEUED', 'dispatchable', ['effect.launchTask']);
+        return emptyWorkflowDecision('no_transition');
     }
     const transition = taskLegacy[from][event];
     if (!transition)
-        return { accepted: false, target: null, guard: null, actions: [], reason: 'no_transition' };
-    return { accepted: true, target: transition.target, guard: transition.guard ?? null, actions: transition.actions ?? [], reason: 'accepted' };
+        return emptyWorkflowDecision('no_transition');
+    return accepted(transition.target, transition.guard ?? null, transition.actions ?? []);
 }
-function jobLegacyDecision(from, event, context) {
+function jobLegacyDecision(from, event, facts) {
     if (event === 'pr.closed') {
-        if ((from === 'DRAFT' || from === 'ACTIVE') && context.notMerged === true) {
-            return { accepted: true, target: 'CANCELLED', guard: 'notMerged', actions: ['cancelJob'], reason: 'accepted' };
+        if ((from === 'DRAFT' || from === 'ACTIVE') && facts.notMerged === true) {
+            return accepted('CANCELLED', 'notMerged', CANCEL_EFFECT);
         }
-        return { accepted: false, target: null, guard: null, actions: [], reason: 'no_transition' };
+        return emptyWorkflowDecision('no_transition');
+    }
+    if (event === 'review.approved' || event === 'implementation.completed') {
+        if (from === 'ACTIVE' && facts.autoMerge === true)
+            return accepted('ACTIVE', 'autoMerge', MERGE_EFFECT);
+        return emptyWorkflowDecision('no_transition');
     }
+    if (event === 'effect.mergePullRequest.failed' && from === 'ACTIVE')
+        return accepted('ACTIVE');
     const transition = jobLegacy[from][event];
     if (!transition)
-        return { accepted: false, target: null, guard: null, actions: [], reason: 'no_transition' };
-    return { accepted: true, target: transition.target, guard: transition.guard ?? null, actions: transition.actions ?? [], reason: 'accepted' };
+        return emptyWorkflowDecision('no_transition');
+    return accepted(transition.target, transition.guard ?? null, transition.actions ?? []);
 }
 function sameDecision(a, b) {
     return a.accepted === b.accepted
@@ -122,7 +132,11 @@ function sameDecision(a, b) {
         && a.guard === b.guard
         && a.reason === b.reason
         && a.actions.length === b.actions.length
-        && a.actions.every((value, index) => value === b.actions[index]);
+        && a.actions.every((value, index) => value === b.actions[index])
+        && a.mutations.length === b.mutations.length
+        && a.mutations.every((value, index) => value === b.mutations[index])
+        && a.effects.length === b.effects.length
+        && a.effects.every((value, index) => value === b.effects[index]);
 }
 function report(kind, jobId, taskId, event, from, facts, legacy, graph) {
     const match = sameDecision(legacy, graph);
@@ -145,26 +159,26 @@ function report(kind, jobId, taskId, event, from, facts, legacy, graph) {
     if (!match && !reporter)
         console.warn(JSON.stringify(diagnostic));
 }
-export function decideTaskLifecycle(task, event, context = {}) {
-    const legacy = taskLegacyDecision(task.state, event, context);
+export function decideTaskLifecycle(task, event, facts = {}) {
+    const legacy = taskLegacyDecision(task.state, event, facts);
     const mode = workflowRolloutMode();
     if (mode === 'legacy')
         return legacy;
-    const graph = graphDecision(taskLifecycleWorkflow, task.state, event, context);
+    const graph = graphWorkflowDecision(taskLifecycleWorkflow, task.state, event, facts);
     if (mode === 'shadow') {
-        report('task', task.jobId ?? 'unknown', task.id, event, task.state, context, legacy, graph);
+        report('task', task.jobId ?? 'unknown', task.id, event, task.state, facts, legacy, graph);
         return legacy;
     }
     return graph;
 }
-export function decideJobLifecycle(job, event, context = {}) {
-    const legacy = jobLegacyDecision(job.state, event, context);
+export function decideJobLifecycle(job, event, facts = {}) {
+    const legacy = jobLegacyDecision(job.state, event, facts);
     const mode = workflowRolloutMode();
     if (mode === 'legacy')
         return legacy;
-    const graph = graphDecision(jobLifecycleWorkflow, job.state, event, context);
+    const graph = graphWorkflowDecision(jobLifecycleWorkflow, job.state, event, facts);
     if (mode === 'shadow') {
-        report('job', job.id, undefined, event, job.state, context, legacy, graph);
+        report('job', job.id, undefined, event, job.state, facts, legacy, graph);
         return legacy;
     }
     return graph;

package/dist/workflow/runtime.js

@@ -0,0 +1,39 @@
+import { classifyWorkflowActions, emptyWorkflowDecision, } from './contracts.js';
+export function graphWorkflowDecision(engine, from, event, facts = {}) {
+    const enabled = engine.enabledSync(from, event, facts);
+    if (enabled.length === 0)
+        return emptyWorkflowDecision('no_transition');
+    if (enabled.length > 1)
+        return emptyWorkflowDecision('ambiguous');
+    const transition = enabled[0];
+    const actions = [...transition.actions];
+    const classified = classifyWorkflowActions(actions);
+    return {
+        accepted: true,
+        target: transition.to,
+        guard: transition.guard,
+        actions,
+        ...classified,
+        reason: 'accepted',
+    };
+}
+function applyTaskMutation(task, mutation) {
+    if (mutation === 'mutation.clearError')
+        task.error = null;
+    if (mutation === 'mutation.clearFailureReason')
+        task.failureReason = undefined;
+}
+export function applyTaskWorkflowDecision(task, decision, timestamp = new Date().toISOString()) {
+    if (!decision.accepted || !decision.target)
+        throw new Error(`Cannot apply rejected workflow decision to task ${task.id}`);
+    task.state = decision.target;
+    for (const mutation of decision.mutations)
+        applyTaskMutation(task, mutation);
+    task.updatedAt = timestamp;
+}
+export function applyJobWorkflowDecision(job, decision, timestamp = new Date().toISOString()) {
+    if (!decision.accepted || !decision.target)
+        throw new Error(`Cannot apply rejected workflow decision to job ${job.id}`);
+    job.state = decision.target;
+    job.updatedAt = timestamp;
+}

package/dist/workflow/task-reconcile.js

@@ -0,0 +1,48 @@
+import { decideTaskLifecycle } from './rollout.js';
+import { applyTaskWorkflowDecision } from './runtime.js';
+export function dependencyReady(task, tasks) {
+    return task.dependencies.every(id => tasks.get(id)?.state === 'SUCCEEDED');
+}
+export function detectCycles(tasks) {
+    const map = new Map(tasks.map(task => [task.id, task]));
+    const visiting = new Set();
+    const done = new Set();
+    const visit = (id) => {
+        if (visiting.has(id))
+            throw new Error(`Dependency cycle at ${id}`);
+        if (done.has(id))
+            return;
+        visiting.add(id);
+        for (const dependency of map.get(id)?.dependencies ?? [])
+            visit(dependency);
+        visiting.delete(id);
+        done.add(id);
+    };
+    for (const task of tasks)
+        visit(task.id);
+}
+function scheduledCycleTasks(job) {
+    const slot = job.schedule?.currentRunSlot ? Date.parse(job.schedule.currentRunSlot) : Number.NaN;
+    if (!Number.isFinite(slot))
+        return job.tasks;
+    return job.tasks.filter(task => Date.parse(task.createdAt) >= slot);
+}
+export function reconcileTaskDependencies(job) {
+    detectCycles(job.tasks);
+    const scopedTasks = scheduledCycleTasks(job);
+    const tasks = new Map(job.tasks.map(task => [task.id, task]));
+    for (const task of scopedTasks) {
+        const ready = dependencyReady(task, tasks);
+        const facts = {
+            dependenciesSatisfied: task.dependencies.length > 0 && ready,
+            dependenciesUnsatisfied: task.dependencies.length > 0 && !ready,
+            runnable: ready,
+        };
+        const decision = decideTaskLifecycle(task, 'reconcile', facts);
+        if (decision.reason === 'ambiguous')
+            throw new Error(`Ambiguous automatic task transition from ${task.state}`);
+        if (decision.accepted && decision.target)
+            applyTaskWorkflowDecision(task, decision);
+    }
+    return job;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "1.0.89",
+  "version": "1.0.91",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
   "bin": {

package/workflow/job-lifecycle.mmd

@@ -2,14 +2,19 @@ stateDiagram-v2
     [*] --> DRAFT
 
     DRAFT --> ACTIVE: activate
-    DRAFT --> COMPLETED: pr.merged
+    DRAFT --> COMPLETED: pr.merged / effect.cancelActiveTasks
     DRAFT --> CANCELLED: cancel
-    DRAFT --> CANCELLED: pr.closed [notMerged] / cancelJob
+    DRAFT --> CANCELLED: pr.closed [notMerged] / effect.cancelActiveTasks
 
-    ACTIVE --> COMPLETED: pr.merged
+    ACTIVE --> ACTIVE: review.approved [autoMerge] / effect.mergePullRequest
+    ACTIVE --> ACTIVE: implementation.completed [autoMerge] / effect.mergePullRequest
+    ACTIVE --> ACTIVE: effect.mergePullRequest.failed
+    ACTIVE --> COMPLETED: pr.merged / effect.cancelActiveTasks
     ACTIVE --> CANCELLED: cancel
-    ACTIVE --> CANCELLED: pr.closed [notMerged] / cancelJob
+    ACTIVE --> CANCELLED: pr.closed [notMerged] / effect.cancelActiveTasks
 
-    CANCELLED --> COMPLETED: pr.merged
+    CANCELLED --> COMPLETED: pr.merged / effect.cancelActiveTasks
+    CANCELLED --> CANCELLED: effect.cancelActiveTasks.failed
+    COMPLETED --> COMPLETED: effect.cancelActiveTasks.failed
 
     COMPLETED --> [*]

package/workflow/task-lifecycle.mmd

@@ -1,30 +1,32 @@
 stateDiagram-v2
     [*] --> DRAFT
 
-    DRAFT --> QUEUED: release
-    DRAFT --> QUEUED: reconcile [dependenciesSatisfied] / release
+    DRAFT --> QUEUED: release / mutation.clearError,mutation.clearFailureReason
+    DRAFT --> QUEUED: reconcile [dependenciesSatisfied] / mutation.clearError,mutation.clearFailureReason
     DRAFT --> BLOCKED: block
     DRAFT --> CANCELLED: cancel
 
     QUEUED --> DRAFT: hold
-    QUEUED --> DRAFT: reconcile [dependenciesUnsatisfied] / hold
-    QUEUED --> QUEUED: reconcile [runnable] / release
-    QUEUED --> RUNNING: task.started
+    QUEUED --> DRAFT: reconcile [dependenciesUnsatisfied]
+    QUEUED --> QUEUED: reconcile [runnable] / mutation.clearError,mutation.clearFailureReason
+    QUEUED --> QUEUED: dispatch [dispatchable] / effect.launchTask
+    QUEUED --> RUNNING: task.started / mutation.clearError,mutation.clearFailureReason
     QUEUED --> BLOCKED: block
     QUEUED --> FAILED: fail
+    QUEUED --> FAILED: effect.launchTask.failed
     QUEUED --> CANCELLED: cancel
 
     RUNNING --> BLOCKED: task.blocked
-    RUNNING --> SUCCEEDED: task.completed
+    RUNNING --> SUCCEEDED: task.completed / mutation.clearError,mutation.clearFailureReason
     RUNNING --> FAILED: task.failed
     RUNNING --> CANCELLED: task.cancelled
 
-    BLOCKED --> QUEUED: retry
+    BLOCKED --> QUEUED: retry / mutation.clearError,mutation.clearFailureReason
     BLOCKED --> CANCELLED: cancel
 
-    FAILED --> QUEUED: retry
-    FAILED --> RUNNING: reconcile.started
-    FAILED --> SUCCEEDED: reconcile.completed
+    FAILED --> QUEUED: retry / mutation.clearError,mutation.clearFailureReason
+    FAILED --> RUNNING: reconcile.started / mutation.clearError,mutation.clearFailureReason
+    FAILED --> SUCCEEDED: reconcile.completed / mutation.clearError,mutation.clearFailureReason
     FAILED --> BLOCKED: reconcile.blocked
     FAILED --> CANCELLED: cancel