agents-relay 2.0.107 → 2.0.108

package/dist/cli-help.js

@@ -8,7 +8,7 @@ Usage:
 --no-github: SQLite/Graph-only mode. GitHub auth/API, PR creation, merge and fetch are disabled. Local completion is Graph-owned.
 
 Commands:
-  job create|update|show|list|merge|unblock|cancel  Manage SQLite-authoritative jobs with optional GitHub PRs
+  job create|update|show|list|merge|unblock|cancel|pause|resume  Manage SQLite-authoritative jobs with optional GitHub PRs
   task create|update|show|list|complete|retry|unblock|cancel  Manage durable tasks
   review request           Request graph-owned review (optional thread override)
   plan                     Invoke the Planner for an existing managed Job
@@ -29,7 +29,7 @@ Use 'node dist/cli.js' only for explicit local development/demo mode.`,
     job: `Manage SQLite-authoritative durable jobs.
 
 Usage:
-  npx agents-relay job <create|update|show|list|merge|unblock|cancel> [options]
+  npx agents-relay job <create|update|show|list|merge|unblock|cancel|pause|resume> [options]
 
 Actions:
   create  Create a durable Job, optionally binding an existing unmanaged PR
@@ -39,6 +39,8 @@ Actions:
   merge   Queue a retryable external PR merge; Graph completes the Job only after confirmation
   unblock Authoritatively invalidate current BLOCKED decisions and trigger replanning/resume
   cancel  Close the backing PR and cancel the Job
+  pause   Persistently stop dispatch and interrupt active generations; lifecycle state remains unchanged
+  resume  Clear pause metadata and requeue interrupted work
 
 Common options:
   --repo OWNER/REPO       GitHub repository
@@ -94,6 +96,12 @@ Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID. The current PR head S
     'job cancel': `Cancel the durable Job and close its backing pull request.
 
 Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID. Nonterminal Tasks are cancelled before the PR is closed.`,
+    'job pause': `Pause a durable Job without inventing a PAUSED lifecycle state.
+
+Required: --repo OWNER/REPO --id JOB_ID. Optional: --pr NUMBER. Running worker and Planner generations are interrupted durably and resume as uncompleted work.`,
+    'job resume': `Resume a paused durable Job.
+
+Required: --repo OWNER/REPO --id JOB_ID. Optional: --pr NUMBER. Interrupted work is requeued and normal reconciliation continues.`,
     escalation: `Run the canonical escalation workflow for a suspected human/external blocker.\n\nRequired: --intent TEXT|--intent-file PATH and --blocked-on TEXT|--blocked-on-file PATH. Optional: --context/--context-file, --on-needs-user/--on-needs-user-file, --cwd. The executable workflow/escalation.mmd graph invokes Neo escalation, then owns the resolved / failed / needs_user branch. Only needs_user selects the block-for-user path.`,
     status: `Show live aggregate runtime status from the running Agents Relay service.
 

package/dist/cli.js

@@ -41,6 +41,7 @@ import { SERVICE_DEFAULTS, ServiceEventBus, arg, hasArg, textOption, integerArg,
 export { SERVICE_DEFAULTS, eventBus, executionMode, chatGptTabClosePolicy } from './cli-support.js';
 import { workerTaskFromArgs } from './cli-worker-task.js';
 import { taskExecutionContext } from './task-context.js';
+import { pauseJob, resumeJob } from './job-pause.js';
 export { ensureManagedGitHubJob } from './cli-job-create.js';
 async function runManagedTaskCommand(action, args) {
     const jobId = arg(args, '--id');
@@ -363,7 +364,7 @@ async function runContextCommand(action, args) {
     console.log(JSON.stringify(context, null, 2));
 }
 async function runJobCommand(action, args) {
-    if (!['create', 'adopt', 'update', 'show', 'list', 'merge', 'unblock', 'cancel'].includes(action))
+    if (!['create', 'adopt', 'update', 'show', 'list', 'merge', 'unblock', 'cancel', 'pause', 'resume'].includes(action))
         throw new Error(usage);
     const repo = repository(args);
     let createObjective;
@@ -400,6 +401,19 @@ async function runJobCommand(action, args) {
     const id = arg(args, '--id');
     if (!id && action !== 'create')
         throw new Error('--id is required for managed local Jobs');
+    if (action === 'pause' || action === 'resume') {
+        const target = await storeFor(args);
+        if (target.job.repository !== repo)
+            throw new Error('Local Job/PR binding mismatch');
+        const prValue = arg(args, '--pr');
+        if (prValue && target.job.prNumber !== Number(prValue))
+            throw new Error('Local Job/PR binding mismatch');
+        const updated = action === 'pause' ? await pauseJob(target.store, id) : await resumeJob(target.store, id);
+        await saveLocal(target.localFile, updated);
+        await withEventBus(args, bus => publishWake(bus, updated, 'job', `Job ${id} ${action} requested`));
+        console.log(JSON.stringify(updated, null, 2));
+        return;
+    }
     const prValue = arg(args, '--pr');
     const prNumber = prValue ? Number(prValue) : 0;
     if (prValue && (!Number.isInteger(prNumber) || (prNumber ?? 0) <= 0))

package/dist/job-pause.js

@@ -0,0 +1,75 @@
+import { tryTransitionTaskEvent } from './scheduler.js';
+export async function pauseJob(store, jobId) {
+    const mutate = (current) => {
+        if (['COMPLETED', 'CANCELLED'].includes(current.state))
+            throw new Error(`Cannot pause terminal Job ${current.id} (${current.state})`);
+        if (current.pause)
+            return current;
+        const now = new Date().toISOString();
+        current.pause = { generation: 1, requestedAt: now };
+        for (const task of current.tasks) {
+            if (task.kind === 'planner' || ['SUCCEEDED', 'FAILED', 'CANCELLED'].includes(task.state))
+                continue;
+            if (task.executionId)
+                task.pausedExecution = { id: task.executionId, state: task.state === 'RUNNING' ? 'RUNNING' : 'QUEUED', attempt: task.attempt, at: now };
+            if (task.state === 'RUNNING' && !tryTransitionTaskEvent(task, 'pause').accepted)
+                throw new Error(`Cannot pause running Task ${task.id}`);
+            task.executionId = null;
+            task.leaseOwner = null;
+            task.leaseExpiresAt = null;
+            task.updatedAt = now;
+        }
+        for (const plan of current.plans ?? []) {
+            if (plan.status !== 'PLANNING')
+                continue;
+            if (plan.executionId)
+                plan.pausedExecutionId = plan.executionId;
+            plan.executionId = null;
+            plan.leaseOwner = null;
+            plan.leaseExpiresAt = null;
+            plan.updatedAt = now;
+        }
+        current.updatedAt = now;
+        return current;
+    };
+    if (store.mutateJob)
+        return store.mutateJob(jobId, mutate);
+    const job = await store.load(jobId);
+    const updated = mutate(job);
+    await store.saveJob(updated);
+    for (const task of updated.tasks)
+        await store.saveTask(task);
+    for (const plan of updated.plans ?? [])
+        await store.savePlan(plan);
+    return updated;
+}
+export async function resumeJob(store, jobId) {
+    const mutate = (current) => {
+        if (!current.pause)
+            return current;
+        const now = new Date().toISOString();
+        delete current.pause;
+        for (const task of current.tasks) {
+            if (task.pausedExecution) {
+                if (task.attempt >= task.maxAttempts)
+                    task.maxAttempts = task.attempt + 1;
+                delete task.pausedExecution;
+                task.updatedAt = now;
+            }
+        }
+        for (const plan of current.plans ?? [])
+            delete plan.pausedExecutionId;
+        current.updatedAt = now;
+        return current;
+    };
+    if (store.mutateJob)
+        return store.mutateJob(jobId, mutate);
+    const job = await store.load(jobId);
+    const updated = mutate(job);
+    await store.saveJob(updated);
+    for (const task of updated.tasks)
+        await store.saveTask(task);
+    for (const plan of updated.plans ?? [])
+        await store.savePlan(plan);
+    return updated;
+}

package/dist/manual-plan.js

@@ -5,6 +5,8 @@ export async function executeManualPlan(store, jobId, guidance, timeoutMs, launc
     let job = await store.load(jobId);
     if (['COMPLETED', 'CANCELLED'].includes(job.state))
         throw new Error(`Cannot plan terminal job ${job.id} (${job.state})`);
+    if (job.pause)
+        throw new Error(`Cannot plan paused Job ${job.id}; resume it first`);
     const active = pendingPlan(job);
     if (active && active.executionId)
         throw new Error(`Planning round ${active.id} is already PLANNING`);
@@ -13,6 +15,8 @@ export async function executeManualPlan(store, jobId, guidance, timeoutMs, launc
         const committed = await store.mutateJob(jobId, current => {
             if (['COMPLETED', 'CANCELLED'].includes(current.state))
                 throw new Error(`Cannot plan terminal job ${current.id} (${current.state})`);
+            if (current.pause)
+                throw new Error(`Cannot plan paused Job ${current.id}; resume it first`);
             const concurrent = pendingPlan(current);
             if (concurrent) {
                 if (concurrent.executionId)

package/dist/planner-runtime.js

@@ -281,6 +281,8 @@ export async function launchPlanExecution(ports, job, plan) {
     }
     const claimed = await withExecutionBoundary(job.id, '__job_execution_slot__', async () => {
         const freshJob = await ports.store.load(job.id);
+        if (freshJob.pause)
+            return null;
         const fresh = (freshJob.plans ?? []).find(item => item.id === plan.id);
         if (!fresh || fresh.status !== 'PLANNING')
             return null;

package/dist/pool.js

@@ -10,6 +10,8 @@ const RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
 export function compareJobPriority(a, b) { return RANK[a.priority ?? 'P2'] - RANK[b.priority ?? 'P2'] || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
 export function runnableManagedJobs(items) { return items.filter(item => item.job.state === 'ACTIVE').map(item => item.job).sort(compareJobPriority); }
 export function needsLifecycleReconciliation(job, now = Date.now()) {
+    if (job.pause)
+        return job.tasks.some(task => Boolean(task.pausedExecution)) || Boolean(job.plans?.some(plan => Boolean(plan.pausedExecutionId)));
     // DRAFT create-only Jobs stay dormant until a caller explicitly creates work.
     if (job.tasks.length === 0)
         return false;

package/dist/reconciler-pause.js

@@ -0,0 +1,11 @@
+/** Stop only generations already invalidated by the durable pause mutation. */
+export function cancelPausedGenerations(job, cancelTask, cancelPlan) {
+    if (!job.pause)
+        return;
+    for (const task of job.tasks)
+        if (task.pausedExecution)
+            cancelTask(task.id, task.pausedExecution.id);
+    for (const plan of job.plans ?? [])
+        if (plan.pausedExecutionId)
+            cancelPlan(plan.id);
+}

package/dist/reconciler.js

@@ -1,3 +1,4 @@
+import { cancelPausedGenerations } from './reconciler-pause.js';
 import { taskCommentContext } from './task-comments.js';
 import { cancelActiveTasks } from './reconciler-cancellation.js';
 import { authorizedInjection } from './e2e-injection.js';
@@ -41,7 +42,7 @@ export class Reconciler extends ReconcilerReviewBase {
         this.workflowEffects.register(new CallbackWorkflowEffectHandler('effect.launchTask', async (context) => {
             const job = await this.store.load(context.jobId);
             const task = context.taskId ? job.tasks.find(item => item.id === context.taskId) : undefined;
-            if (!task || task.state !== 'QUEUED' || task.executionId !== null)
+            if (!task || job.pause || task.state !== 'QUEUED' || task.executionId !== null)
                 return;
             if (task.kind !== 'planner' && task.adapter !== 'orchestrator')
                 await this.launch(job, task);
@@ -51,6 +52,8 @@ export class Reconciler extends ReconcilerReviewBase {
     }
     async dispatchExecutableTasks(jobId) {
         const scheduled = schedule(await this.store.load(jobId));
+        if (scheduled.pause)
+            return scheduled;
         for (const task of scheduled.tasks.filter(item => item.state === 'SUCCEEDED' && (item.continuation || scheduled.continuation) && !item.continuationDeliveredAt)) {
             this.detach(this.deliverContinuation(scheduled, task), scheduled.id, task.id, 'continuation');
         }
@@ -92,6 +95,14 @@ export class Reconciler extends ReconcilerReviewBase {
             }
             await this.invalidateStaleReview(job, headSha);
             const now = (this.options.now ?? new Date()).getTime();
+            if (job.pause) {
+                cancelPausedGenerations(job, (taskId, executionId) => this.cancelExecutionGeneration(job.id, taskId, executionId), planId => { const live = this.plannerLive.get(planId); if (live) {
+                    clearTimeout(live.timer);
+                    live.controller.abort();
+                    this.plannerLive.delete(planId);
+                } });
+                return job;
+            }
             if (job.state !== 'ACTIVE')
                 return job;
             await recoverExpiredExecutions(job, now, this.executionRecoveryPorts(job));

package/dist/scheduler.js

@@ -17,6 +17,8 @@ export function completionGateSatisfied(job) {
     return (planSatisfied || legacySatisfied) && implementationTasks(job).every(task => task.state === 'SUCCEEDED');
 }
 export function schedule(job) {
+    if (job.pause)
+        return job;
     reconcileTaskDependencies(job);
     const scopedTasks = job.schedule?.currentRunSlot
         ? job.tasks.filter(task => Date.parse(task.createdAt) >= Date.parse(job.schedule?.currentRunSlot ?? ''))

package/dist/workflow/contracts.js

@@ -19,6 +19,7 @@ export const WORKFLOW_EVENT_NAMES = [
     'pr.merged',
     'queue',
     'plan.requested',
+    'pause',
     'planner.failed',
     'planner.unavailable',
     'reconcile',

package/package.json

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

package/workflow/task-lifecycle.mmd

@@ -178,6 +178,7 @@ leaseFailRunningMark --> leaseFailRunningClearLease
 leaseFailRunningClearLease --> leaseFailRunningClearExecution
 leaseFailRunningClearExecution --> failed
 running -->|on: task.cancelled| cancelled
+running -->|on: pause| queued
 running -->|on: cancel| cancelled
 
 autonomousJob["guard: autonomousJob"]