agents-relay 1.0.81 → 1.0.83

package/README.md

@@ -182,4 +182,6 @@ npx agents-relay task create --repo OWNER/REPO --pr 5 --id job-1 \
 
 GitHub PR state is authoritative for terminal lifecycle: a merged PR reconciles its managed job to `COMPLETED`; a closed, unmerged PR reconciles to `CANCELLED` and cannot launch queued work. The dashboard exposes `/api/jobs` and shows PR state, durable Job lifecycle, and derived runtime status separately. A merged PR reconciles lifecycle to `COMPLETED`; a closed, unmerged PR reconciles lifecycle to `CANCELLED`.
 
+`adapter: orchestrator` is reserved for synchronous self-work by the exact orchestrator turn that creates the Task. Relay deliberately does not auto-start these Tasks during reconciliation. The creator must perform the work before ending the turn and terminalize the same Task with `npx agents-relay task complete --task-id <id> --summary <summary> ...`. If work should continue asynchronously or in a later turn, use a real worker adapter instead.
+
 For work that was completed outside the relay but must be represented truthfully in durable history, use `npx agents-relay record --task-id <id> --summary <summary> --commit <sha>`. Recorded tasks use the `orchestrator` adapter and terminal `SUCCEEDED` state; they do not pretend a shell/model worker executed the work. This is a repair/backfill mechanism—normal work should be created as a durable Task before execution. For managed jobs, the GitHub PR body is the canonical Job surface: hidden Job metadata marker plus the visible Markdown objective.

package/dist/cli.js

@@ -28,7 +28,7 @@ Usage:
 
 Commands:
   job create|update|show|list|merge|cancel  Manage durable GitHub-backed jobs
-  task create|update|show|list|retry|cancel  Manage durable tasks
+  task create|update|show|list|complete|retry|cancel  Manage durable tasks
   context resolve          Resolve shared project instructions, skills, agents, and runtimes
   init                     Create a local demo job or initialize a GitHub job
   record                   Backfill a completed task into durable history
@@ -106,6 +106,7 @@ Actions:
   show    Show one Task
   list    List Tasks for a Job
   retry   Retry a failed or blocked Task
+  complete Complete an orchestrator-owned Task
   cancel  Cancel a Task`,
     'task create': `Create one durable Task under an existing Job.
 
@@ -129,6 +130,9 @@ Required: --task-id ID and the normal Job storage options.`,
     'task list': `List durable Tasks for one Job.
 
 Required: the normal Job storage options.`,
+    'task complete': `Complete one orchestrator-owned Task after the creating orchestrator has finished the work.
+
+Required: --task-id ID, --summary TEXT, and the normal Job storage options. The Task must use adapter=orchestrator and be QUEUED or RUNNING. This command is for the same orchestrator turn that created the self-task; it is not a deferred handoff mechanism.`,
     'task retry': `Retry one durable Task.
 
 Required: --task-id ID and the normal Job storage options.`,
@@ -402,7 +406,7 @@ async function workerTaskFromArgs(job, args, now) {
     };
 }
 async function runTaskCommand(action, args) {
-    if (!['create', 'update', 'show', 'list', 'retry', 'cancel'].includes(action))
+    if (!['create', 'update', 'show', 'list', 'complete', 'retry', 'cancel'].includes(action))
         throw new Error(usage);
     const { store, job, localFile } = await storeFor(args);
     if (action === 'list') {
@@ -437,6 +441,28 @@ async function runTaskCommand(action, args) {
         console.log(JSON.stringify(task, null, 2));
         return;
     }
+    if (action === 'complete') {
+        if (task.adapter !== 'orchestrator')
+            throw new Error('task complete is only valid for adapter=orchestrator self-tasks');
+        if (!['QUEUED', 'RUNNING'].includes(task.state))
+            throw new Error(`Task ${id} is ${task.state}; only QUEUED or RUNNING orchestrator tasks can be completed`);
+        const summary = arg(args, '--summary');
+        if (!summary)
+            throw new Error('task complete requires --summary');
+        if (task.state === 'QUEUED')
+            await transitionTaskEvent(task, 'task.started');
+        task.attempt = Math.max(task.attempt, 1);
+        task.result = { summary };
+        task.error = null;
+        task.leaseOwner = null;
+        task.leaseExpiresAt = null;
+        task.executionId = null;
+        await transitionTaskEvent(task, 'task.completed');
+        await store.saveTask(task);
+        await saveLocal(localFile, await store.load(job.id));
+        console.log(JSON.stringify(task, null, 2));
+        return;
+    }
     if (action === 'retry' || action === 'cancel') {
         if (action === 'retry')
             task.maxAttempts = extendRetryBudget(task);

package/dist/dashboard.js

@@ -286,7 +286,7 @@ function actionButton(job,action,label,icon){const button=document.createElement
 async function runJobAction(job,action,button){button.disabled=true;try{const response=await fetch('/api/job-action?id='+encodeURIComponent(job.id)+'&action='+encodeURIComponent(action),{method:'POST'});if(!response.ok)throw new Error(response.status+' '+response.statusText);await refresh(true);}catch(error){button.title=labelForAction(action)+': '+error.message;}finally{renderAll();}}
 function labelForAction(action){return action==='start'?'Start':action==='reconcile'?'Reconcile':'Cancel';}
 function repoName(repository){if(typeof repository!=='string'||!repository)return 'unknown-repo';const parts=repository.split('/').filter(Boolean);return parts.at(-1)||repository;}
-function renderJobList(){jobList.replaceChildren();const visible=filteredJobs();if(!jobs.length){jobList.append(element('li','empty',text('No durable jobs discovered.')));return;}if(!visible.length){jobList.append(element('li','empty',text('No jobs match the selected repo.')));return;}for(const job of visible){const row=element('div','job-row'+(isCompleteUnmerged(job)?' complete-unmerged':''));row.setAttribute('aria-current',String(job.id===selectedJob));row.addEventListener('click',()=>selectJob(job.id));const content=element('div','job-content');const select=document.createElement('button');select.type='button';select.className='job-button';select.setAttribute('aria-current',String(job.id===selectedJob));select.title=job.title||job.id;select.addEventListener('click',event=>{event.stopPropagation();selectJob(job.id);});select.append(element('span','job-title',text(repoName(job.repository)+'/PR#'+value(job.prNumber)+': '+value(job.title||job.id))));const states=element('span','job-status-line');states.append(element('span','badge '+value(job.state),text(value(job.state))),element('span','badge '+value(job.runtimeStatus||'IDLE'),text(value(job.runtimeStatus||'IDLE'))),element('span','badge '+value(job.githubState||'UNKNOWN'),text(value(job.githubState||'UNKNOWN'))));if(job.executionMode==='autonomous')states.append(element('span','badge flag-autonomous',text('AUTONOMOUS')));if(job.reviewEnabled!==false)states.append(element('span','badge flag-review',text('REVIEW REQUIRED')));if(isCompleteUnmerged(job))states.append(element('span','badge MERGE_PENDING',text('MERGE PENDING')));const actions=element('span','job-actions');actions.append(actionButton(job,'start','Start','▶'),actionButton(job,'reconcile','Reconcile','↻'),actionButton(job,'cancel','Cancel','×'));const primary=element('div','job-primary');primary.append(states,actions);const lastLine=element('div','job-last-line');lastLine.append(element('span','subtle',text(compactCounts(counts(job.tasks)))),element('span','subtle',text(relativeTime(job.updatedAt))));content.append(select,primary,lastLine);row.append(content);jobList.append(element('li','',row));}}
+function renderJobList(){jobList.replaceChildren();const visible=filteredJobs();if(!jobs.length){jobList.append(element('li','empty',text('No durable jobs discovered.')));return;}if(!visible.length){jobList.append(element('li','empty',text('No jobs match the selected repo.')));return;}for(const job of visible){const row=element('div','job-row'+(isCompleteUnmerged(job)?' complete-unmerged':''));row.setAttribute('aria-current',String(job.id===selectedJob));row.addEventListener('click',()=>selectJob(job.id));const content=element('div','job-content');const select=document.createElement('button');select.type='button';select.className='job-button';select.setAttribute('aria-current',String(job.id===selectedJob));select.title=job.title||job.id;select.addEventListener('click',event=>{event.stopPropagation();selectJob(job.id);});select.append(element('span','job-title',text(repoName(job.repository)+'/PR#'+value(job.prNumber)+': '+value(job.title||job.id))));const states=element('span','job-status-line');states.append(element('span','badge '+value(job.state),text(value(job.state))),element('span','badge '+value(job.runtimeStatus||'IDLE'),text(value(job.runtimeStatus||'IDLE'))));if(job.executionMode==='autonomous')states.append(element('span','badge flag-autonomous',text('AUTONOMOUS')));if(job.reviewEnabled!==false)states.append(element('span','badge flag-review',text('REVIEW REQUIRED')));if(isCompleteUnmerged(job))states.append(element('span','badge MERGE_PENDING',text('MERGE PENDING')));const actions=element('span','job-actions');actions.append(actionButton(job,'start','Start','▶'),actionButton(job,'reconcile','Reconcile','↻'),actionButton(job,'cancel','Cancel','×'));const primary=element('div','job-primary');primary.append(states,actions);const lastLine=element('div','job-last-line');lastLine.append(element('span','subtle',text(compactCounts(counts(job.tasks)))),element('span','subtle',text(relativeTime(job.updatedAt))));content.append(select,primary,lastLine);row.append(content);jobList.append(element('li','',row));}}
 function taskNode(task,children,depth){const li=element('li');const row=document.createElement('button');row.type='button';row.className='task-row';row.setAttribute('aria-current',String(task.id===selectedTaskId));row.title=task.id;row.addEventListener('click',()=>{selectedTaskId=task.id;eventTaskId=task.id;rememberSelection();clearEvents();renderAll();void loadEventHistory();});const id=element('span','task-id',text(task.id));id.style.paddingLeft=Math.min(depth,4)*6+'px';row.append(id,element('span','badge '+value(task.state),text(task.state)));li.append(row);const nested=children.get(task.id)||[];if(nested.length){const ul=element('ul','tree');for(const child of nested)ul.append(taskNode(child,children,depth+1));li.append(ul);}return li;}
 function buildTree(tasks){taskTree.replaceChildren();if(!Array.isArray(tasks)||!tasks.length){taskTree.append(element('li','empty',text('No tasks in durable state.')));return;}const known=new Set(tasks.map(task=>task.id));const children=new Map();const roots=[];for(const task of tasks){if(!task.parentTaskId||!known.has(task.parentTaskId))roots.push(task);else{const siblings=children.get(task.parentTaskId)||[];siblings.push(task);children.set(task.parentTaskId,siblings);}}for(const task of roots)taskTree.append(taskNode(task,children,0));}
 function attemptBudget(task){const attempt=Number(task?.attempt)||0;const max=Number(task?.maxAttempts)||0;if(max>=3&&max%3===0){const effectiveMax=Math.max(max,Math.ceil(attempt/3)*3);return attempt+' / 3×'+(effectiveMax/3);}return attempt+' / '+max;}

package/dist/reconciler.js

@@ -187,15 +187,7 @@ export class Reconciler {
                 for (const task of scheduled.tasks.filter(t => t.state === 'QUEUED' && t.executionId === null && dependencyReady(t, new Map(scheduled.tasks.map(item => [item.id, item])))).sort((a, b) => compareTaskPriority(a, b, scheduled.priority ?? 'P2')).slice(0, capacity)) {
                     if (task.kind === 'planner')
                         await this.launchPlanner(scheduled, task);
-                    else if (task.adapter === 'orchestrator') {
-                        await transitionTaskEvent(task, 'task.started');
-                        task.leaseOwner = null;
-                        task.leaseExpiresAt = null;
-                        task.executionId = null;
-                        await this.store.saveTask(task);
-                        await this.emit(eventFor(scheduled.id, task.id, task.parentTaskId, 'task.orchestrator_assigned', 'running', `Task ${task.id} assigned to orchestrator self`, 'orchestrator', { adapter: 'orchestrator' }, { agent: 'relay', component: 'agents-relay' }));
-                    }
-                    else
+                    else if (task.adapter !== 'orchestrator')
                         await this.launch(scheduled, task);
                 }
             }

package/package.json

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

package/skills/agents-relay/contracts/orchestrator-workflows.md

@@ -23,8 +23,9 @@ A **P0 job** (alias: **self job**) is executed directly by the current active or
 
 1. The orchestrator creates the durable job.
 2. The orchestrator immediately creates the required orchestrator-owned task(s); do not leave the P0 job idle.
-3. The current orchestrator thread starts executing those tasks immediately rather than delegating them to another worker.
-4. P0/self jobs do not require the normal reviewer gate unless the user explicitly asks for review.
-5. After implementation and local verification, the orchestrator merges the job itself and completes normal post-merge reconciliation.
+3. The current orchestrator thread starts executing those tasks immediately rather than delegating them to another worker. Creating an `adapter: orchestrator` Task is never a handoff: the exact creator owns it for this turn.
+4. The orchestrator must terminalize every orchestrator-owned Task it created before ending the turn. It must not return to the user with one of its self-tasks left `QUEUED` or `RUNNING`; successful work uses `task complete` on that same durable Task.
+5. P0/self jobs do not require the normal reviewer gate unless the user explicitly asks for review.
+6. After implementation and local verification, the orchestrator merges the job itself and completes normal post-merge reconciliation.
 
 `job create` still only creates durable job state; the P0 workflow requires the orchestrator to follow it immediately with task creation and execution.

package/skills/agents-relay/contracts/task-job-contract.md

@@ -87,6 +87,16 @@ Task readiness is explicit and must use these semantics:
 
 Do not use `WAITING` as a Task state or durable Job lifecycle state. `WAITING` is a derived Job runtime status for an `ACTIVE` Job whose next progress depends on a future trigger, schedule slot, dependency release, or other condition.
 
+## Orchestrator self-task ownership
+
+A Task with `adapter: orchestrator` is synchronous self-work owned by the exact orchestrator turn that creates it. It is not a durable handoff to Relay, another worker, a later reconcile cycle, or a future orchestrator thread.
+
+- Creating an `adapter: orchestrator` Task is an execution commitment: the creating orchestrator must execute it in the current turn.
+- The creating orchestrator must not end its turn while any orchestrator Task it created remains `QUEUED` or `RUNNING`; it must drive each such Task to a terminal state before returning control to the user.
+- Relay must not auto-start, lease, route, or emit synthetic `task.started` / assignment evidence for orchestrator Tasks. A queued orchestrator Task means the creator has not yet terminalized its self-work.
+- Successful self-work is terminalized on the same durable Task with `task complete --task-id ... --summary ...`; do not use `record` as a substitute for a Task that was created before execution. `record` remains a backfill mechanism for work that genuinely happened outside Relay.
+- If work is intended to survive the current turn or be picked up asynchronously, use a real worker adapter rather than `orchestrator`.
+
 ## Worker lifecycle
 
 Relay owns process lifecycle. Workers own semantic task lifecycle. A worker must publish canonical `task.started` as its first execution action, then exactly one of `task.completed`, `task.failed`, `task.blocked`, or `task.cancelled`. Process launch/exit events do not substitute for worker semantic events.