agents-relay 1.0.82 → 1.0.84

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/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.82",
+  "version": "1.0.84",
   "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.