agents-relay 2.0.106 → 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/dashboard-html.js

@@ -335,7 +335,7 @@ function field(label,input){const box=element('div','detail-group');box.append(e
 function threadField(label,threadId){const box=element('div','detail-group');box.append(element('p','detail-label',text(label)));const id=String(threadId||'').trim();if(!/^[0-9a-f]{8}-[0-9a-f-]{27,}$/i.test(id)){box.append(element('p','detail-value',text(id||'—')));return box;}const link=document.createElement('a');link.className='detail-value';link.href='https://chatgpt.com/c/'+encodeURIComponent(id);link.target='implementation';link.rel='noopener noreferrer';link.textContent=id.slice(0,8);link.title=id;box.append(link);return box;}function markdownField(label,input){const box=element('div','detail-group');box.append(element('p','detail-label',text(label)),markdownValue(input));return box;}
 function rememberSelection(){if(selectedJob)sessionStorage.setItem('agents-relay:selected-job',selectedJob);else sessionStorage.removeItem('agents-relay:selected-job');if(selectedTaskId)sessionStorage.setItem('agents-relay:selected-task',selectedTaskId);else sessionStorage.removeItem('agents-relay:selected-task');}
 function syncMobileJobsView(){const detail=mobileJobs.matches&&Boolean(selectedJob)&&location.hash.startsWith('#/jobs/');document.body.dataset.mobileJobsView=detail?'detail':'list';}
-function shortManagedId(id,repository,kind){const parts=String(repository||'').split('/');if(parts.length!==2)return String(id||'');const prefix=kind+'-'+parts[0].length+'-'+parts[0]+'-'+parts[1]+'-';const value=String(id||'');const suffix=value.startsWith(prefix)?value.slice(prefix.length):'';return /^[0-9]+$/.test(suffix)?'#'+suffix:value;}function jobSelectionKey(job){return job?String(job.repository||'')+'|'+String(job.prNumber||'')+'|'+String(job.id||''):'';}
+function shortManagedId(id,repository,kind){const parts=String(repository||'').split('/');if(parts.length!==2)return String(id||'');const prefix=kind+'-'+parts[0].length+'-'+parts[0]+'-'+parts[1]+'-';const value=String(id||'');const suffix=value.startsWith(prefix)?value.slice(prefix.length):'';return /^[0-9]+$/.test(suffix)?'#'+suffix:value;}function jobSelectionKey(job){return job?String(job.repository||'')+'|'+String(job.id||''):'';}function dedupeJobs(entries){const byId=new Map();for(const job of entries){const key=jobSelectionKey(job);if(!key)continue;const existing=byId.get(key);if(!existing){byId.set(key,job);continue;}const fresh=isFreshEnough(job.updatedAt,existing.updatedAt);const preferred=fresh?job:existing;const other=fresh?existing:job;byId.set(key,{...other,...preferred,prNumber:Number(preferred.prNumber||0)>0?preferred.prNumber:other.prNumber});}return [...byId.values()];}
 function jobForSelection(selection){return jobs.find(job=>jobSelectionKey(job)===selection)||jobs.find(job=>job.id===selection)||null;}
 function selected(){return jobForSelection(selectedJob)||jobs[0]||null;}
 function counts(tasks){const out={};for(const task of Array.isArray(tasks)?tasks:[])out[task.state]=(out[task.state]||0)+1;return out;}
@@ -421,7 +421,7 @@ function renderRateLimitStatus(status){
 function runtimePill(label,value){const pill=element('span','runtime-stat');pill.append(document.createTextNode(label+' '),element('strong','',text(value)));return pill;}
 async function drawRuntimeSummary(){try{const summary=await loadJSON('/api/runtime-summary');runtimeSummary.replaceChildren(runtimePill('Active Jobs',summary.activeJobs||0),runtimePill('Running Tasks',summary.runningTasks||0),runtimePill('ChatGPT',summary.workers?.chatgpt||0),runtimePill('Codex',summary.workers?.codex||0));for(const item of Array.isArray(summary.models)?summary.models:[])runtimeSummary.append(runtimePill(item.model,item.count));}catch{runtimeSummary.replaceChildren();}}
 async function refreshStatus(){try{renderRateLimitStatus(await loadJSON('/api/status'));}catch{renderRateLimitStatus(null);}}
-async function refresh(force=false){jobsRefresh.disabled=true;jobsRefresh.textContent='Refreshing…';try{const discovered=await loadJSON('/api/jobs'+(force?'?refresh=1':''));jobs=Array.isArray(discovered)?discovered:[];void drawRuntimeSummary();jobs.sort(compareJobs);if(selectedJob&&!jobForSelection(selectedJob)){selectedJob=null;selectedTaskId=null;}if(!selectedJob){const match=location.hash.match(/^#\\/jobs\\/(.+)$/);const fromHash=match?decodeURIComponent(match[1]):null;const fromRoute=jobForSelection(fromHash);selectedJob=jobSelectionKey(fromRoute||jobs[0]);}rememberSelection();renderAll();void loadEventHistory();connection.textContent='';connection.setAttribute('aria-label','Live durable state connected');connection.className='status-pill ok';}catch(error){connection.textContent='';connection.setAttribute('aria-label','Durable state unavailable');connection.className='status-pill bad';jobList.replaceChildren(element('li','error-state',text('Could not load jobs: '+error.message)));}finally{jobsRefresh.disabled=false;jobsRefresh.textContent='Refresh';}}
+async function refresh(force=false){jobsRefresh.disabled=true;jobsRefresh.textContent='Refreshing…';try{const discovered=await loadJSON('/api/jobs'+(force?'?refresh=1':''));jobs=dedupeJobs(Array.isArray(discovered)?discovered:[]);void drawRuntimeSummary();jobs.sort(compareJobs);if(selectedJob&&!jobForSelection(selectedJob)){selectedJob=null;selectedTaskId=null;}if(!selectedJob){const match=location.hash.match(/^#\\/jobs\\/(.+)$/);const fromHash=match?decodeURIComponent(match[1]):null;const fromRoute=jobForSelection(fromHash);selectedJob=jobSelectionKey(fromRoute||jobs[0]);}rememberSelection();renderAll();void loadEventHistory();connection.textContent='';connection.setAttribute('aria-label','Live durable state connected');connection.className='status-pill ok';}catch(error){connection.textContent='';connection.setAttribute('aria-label','Durable state unavailable');connection.className='status-pill bad';jobList.replaceChildren(element('li','error-state',text('Could not load jobs: '+error.message)));}finally{jobsRefresh.disabled=false;jobsRefresh.textContent='Refresh';}}
 function renderEventScope(){const task=eventTaskId&&selected()?.tasks?.find(candidate=>candidate.id===eventTaskId);eventsAllTasks.disabled=!task;eventsAllTasks.setAttribute('aria-pressed',String(!task));eventsScope.textContent=task?'Task '+task.id+' · newest first · 60 max':'Job-wide · newest first · 60 max';}
 function eventLabel(type){return ({'task.process.launched':'Process launched','task.started':'Worker started','task.process.exited':'Sync process exited','task.process.async_exited':'Async process exited','task.completed':'Worker completed','task.failed':'Worker failed','task.blocked':'Worker blocked','review.started':'Review started','review.approved':'Review approved','review.changes_required':'Review changes required','review.blocked':'Review blocked'})[type]||type||'Event';}
 function eventSeverity(event,level){const type=String(event?.type||'').toLowerCase(),eventLevel=String(event?.level||level||'').toLowerCase(),outcome=String(event?.outcome||event?.status||'').toLowerCase();if(eventLevel==='error'||outcome==='failed'||type.endsWith('.failed')||type==='task.failed')return 'error';if(eventLevel==='warn'||outcome==='blocked'||type.endsWith('.blocked')||type==='task.blocked'||type==='review.blocked')return 'warn';return 'normal';}
@@ -484,7 +484,7 @@ window.addEventListener('keydown',event=>{if(event.key==='Tab'&&event.altKey){ev
 function parseMessage(message){try{return JSON.parse(message.data);}catch{return null;}}
 function isFreshEnough(incoming,current){const a=Date.parse(incoming||''),b=Date.parse(current||'');return !Number.isFinite(b)||!Number.isFinite(a)||a>=b;}
 function applyStatePatch(patch){if(!patch?.jobId)return false;const job=jobs.find(candidate=>candidate.id===patch.jobId);if(!job)return false;if(patch.jobState&&isFreshEnough(patch.jobUpdatedAt,job.updatedAt)){job['state']=patch.jobState;if(patch.jobUpdatedAt)job.updatedAt=patch.jobUpdatedAt;}if(patch.taskId&&patch.taskState){const task=(job.tasks||[]).find(candidate=>candidate.id===patch.taskId);if(task&&isFreshEnough(patch.taskUpdatedAt,task.updatedAt)){task['state']=patch.taskState;if(patch.taskUpdatedAt)task.updatedAt=patch.taskUpdatedAt;}}return true;}
-function upsertFreshJob(incoming){if(!incoming)return;const index=jobs.findIndex(job=>jobSelectionKey(job)===jobSelectionKey(incoming));if(index<0){jobs.push(incoming);return;}if(isFreshEnough(incoming.updatedAt,jobs[index].updatedAt))jobs[index]=incoming;}
+function upsertFreshJob(incoming){if(!incoming)return;const index=jobs.findIndex(job=>jobSelectionKey(job)===jobSelectionKey(incoming));if(index<0){jobs.push(incoming);return;}if(isFreshEnough(incoming.updatedAt,jobs[index].updatedAt))jobs[index]={...incoming,prNumber:Number(incoming.prNumber||0)>0?incoming.prNumber:jobs[index].prNumber};}
 const stream=new EventSource('/events');
 stream.onopen=()=>{connection.textContent='';connection.setAttribute('aria-label','Event stream connected');connection.className='status-pill ok';};
 stream.onerror=()=>{connection.textContent='';connection.setAttribute('aria-label','Event stream reconnecting');connection.className='status-pill warn';};

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.106",
+  "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"]