agents-relay 1.0.28 → 1.0.30

package/README.md

@@ -38,6 +38,8 @@ autonomous runtime uses the bundled `skills/agents-relay/agents/planner.agent.md
 snapshot as JSON on stdin and must return `{ "objective_status": "in_progress"|"satisfied", "assessment": "...", "next_tasks": [...] }`.
 Planner-created tasks use stable IDs and the existing parent/subtask tree, so
 retries and daemon restarts do not create duplicate work.
+Task producers must follow `skills/agents-relay/contracts/task-job-contract.md`; that shared skill contract defines story size, lifecycle events, review, and auto-merge semantics.
+All task producers use the same story-size contract: `S`≈5 minutes, `M`≈15 minutes, and `L`≈45 minutes of normal-reasoning execution, with `M` as the default. `high` reasoning doubles that overall window. ChatGPT Browser Worker start-ack timeout is derived as one third of the effective overall timeout, clamped between 1 and 5 minutes. Orchestrators and planners should choose `storySize`, not raw timeout milliseconds; `--timeout` remains only as an explicit compatibility/debug override.
 
 job create first resolves an existing open PR with the same head/base, then creates it only when needed. Re-running it is idempotent: it reuses the PR and maintains exactly one trusted agents-relay:job:v1 marker.
 Use `--start` to create/reuse the job and submit its initial task in one invocation. Start mode requires explicit `--adapter`, `--model`, `--output`, and non-empty `--input`; the task ID defaults to `initial`. Re-running with the same task definition reuses that task and never duplicates it. Omitting `--start` preserves create-only behavior, leaving an `OPEN` job with zero tasks until a caller submits work.

package/dist/cli.js

@@ -99,7 +99,7 @@ Example:
     submit: `Queue a task for a managed job.
 
 Required: --repo OWNER/REPO, --pr NUMBER, --id JOB_ID, and --input TEXT.
-Required for worker tasks: --adapter codex|chatgpt, --model MODEL, and --output task-pr|file. File output also requires --output-path PATH.\nCommon: --task-id ID, --priority P0|P1|P2|P3, --max-attempts N. Model-backed execution requires --events nats in the running reconciler/daemon.
+Required for worker tasks: --adapter codex|chatgpt, --model MODEL, and --output task-pr|file. File output also requires --output-path PATH.\nCommon: --task-id ID, --priority P0|P1|P2|P3, --story-size S|M|L, --max-attempts N. Story size defaults to M. Task producers follow the shared Task / Job Contract; prefer --story-size over raw --timeout. Model-backed execution requires --events nats in the running reconciler/daemon.
 
 Example:
   npx agents-relay submit --repo OWNER/REPO --pr 12 --id job-1 --task-id build --adapter codex --provider openai --model gpt-5-6 --output task-pr --input "Run the required tests and report the result through events."`,
@@ -440,7 +440,7 @@ async function runJobCommand(action, args) {
     console.log(JSON.stringify({ repository: repo, pr: result.pr.number, job: result.job.id, executionMode: result.job.executionMode, state: result.job.state, task: start ? arg(args, '--task-id', 'initial') : undefined }, null, 2));
 }
 export function runtimePlanner(args) { const plannerCommand = arg([...args], '--planner-command'); const modelRuntime = arg([...args], '--codex', 'codex'); return plannerCommand ? new CommandObjectivePlanner(plannerCommand) : new AgentObjectivePlanner(modelRuntime); }
-export function runtimeReviewer() { return { adapter: 'chatgpt', routing: { provider: 'chatgpt', model: 'account-defaults', decidedBy: 'fixed-chatgpt-reviewer', decidedAt: new Date().toISOString() }, startAckTimeoutMs: 120000 }; }
+export function runtimeReviewer() { return { adapter: 'chatgpt', routing: { provider: 'chatgpt', model: 'account-defaults', decidedBy: 'fixed-chatgpt-reviewer', decidedAt: new Date().toISOString() } }; }
 export function runtime(store, args, bus) { const emit = (event) => { process.stderr.write(`${JSON.stringify(event)}\n`); }; const modelRuntime = arg(args, '--codex', 'codex'); const policy = chatGptTabClosePolicy(args); const planner = runtimePlanner(args); return new Reconciler(store, { owner: arg(args, '--owner', `cli-${process.pid}`), maxConcurrent: Number(arg(args, '--concurrency', '4')), leaseMs: Number(arg(args, '--lease-ms', '300000')), adapters: [new CodexAdapter(modelRuntime), new ChatGptAdapter({ tabClosePolicy: policy })], continuations: [new CodexThreadContinuation(modelRuntime), new CommandContinuation(), new WebhookContinuation()], planner, reviewer: runtimeReviewer(), eventBus: bus, emit, chatgptTabClosePolicy: policy }); }
 export async function createService(args) {
     const loaded = await storeFor(args);

package/dist/planner.js

@@ -140,6 +140,7 @@ export class CommandObjectivePlanner {
     }
 }
 const DEFAULT_PLANNER_AGENT = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', 'agents-relay', 'agents', 'planner.agent.md');
+const DEFAULT_TASK_JOB_CONTRACT = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', 'agents-relay', 'contracts', 'task-job-contract.md');
 function parsePlannerAgentMessage(line) {
     try {
         const value = JSON.parse(line);
@@ -162,7 +163,8 @@ export class AgentObjectivePlanner {
     }
     async plan(context, signal) {
         const instructions = await readFile(this.agentFile, 'utf8');
-        const prompt = instructions.trim() + '\n\n## Durable planner input\n\n' + plannerInput(context);
+        const contract = await readFile(DEFAULT_TASK_JOB_CONTRACT, 'utf8');
+        const prompt = instructions.trim() + '\n\n## Shared Task / Job Contract\n\n' + contract.trim() + '\n\n## Durable planner input\n\n' + plannerInput(context);
         return await new Promise((resolve, reject) => {
             const child = spawn(this.command, ['exec', '--json', '--', prompt], { stdio: ['ignore', 'pipe', 'pipe'] });
             let stdoutBuffer = '';

package/dist/reconciler.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { storySizeTimeoutMs, taskOverallTimeoutMs } from './types.js';
+import { storySizeTimeoutMs, taskOverallTimeoutMs, chatGptStartAckTimeoutMs } from './types.js';
 import { schedule, transitionTask } from './scheduler.js';
 import { LaunchFailure, StartAckTimeout } from './adapters.js';
 import { eventFor } from './events.js';
@@ -71,7 +71,7 @@ export class Reconciler {
     }
     async handleEvent(event) {
         if (event.type === 'task.started') {
-            this.markWorkerStarted(event);
+            await this.markWorkerStarted(event);
             return;
         }
         if (['task.completed', 'task.failed', 'task.blocked', 'task.cancelled'].includes(event.type)) {
@@ -343,7 +343,7 @@ export class Reconciler {
         const controller = new AbortController();
         let execution;
         const workerTask = { ...task, input: workerInput };
-        const startAckSetup = task.adapter === 'chatgpt' ? await this.startAck(job.id, task.id, Date.now(), task.agentName === 'reviewer' ? this.options.reviewer?.startAckTimeoutMs : undefined) : null;
+        const startAckSetup = task.adapter === 'chatgpt' ? await this.startAck(job.id, task.id, Date.now(), this.options.startAckTimeoutMs ?? chatGptStartAckTimeoutMs(task.timeoutMs)) : null;
         const closePolicy = task.chatgptTabClosePolicy ?? this.options.chatgptTabClosePolicy ?? adapter.tabClosePolicy ?? 'after-start';
         const terminalWait = task.adapter === 'chatgpt' && closePolicy === 'after-terminal'
             ? this.terminalWait(task.id, durableExecutionId, startedAt - 1)
@@ -512,17 +512,44 @@ export class Reconciler {
             clearTimeout(graceTimer);
         this.terminalExitGraceTimers.delete(taskId);
     }
-    markWorkerStarted(event) {
-        const live = this.live.get(event.task_id);
-        if (!live || event.job_id !== live.jobId)
-            return;
+    async markWorkerStarted(event) {
         const sourceAgent = typeof event.source?.agent === 'string' ? event.source.agent : '';
         const sourceComponent = typeof event.source?.component === 'string' ? event.source.component : '';
         if (sourceAgent === 'relay' || sourceComponent === 'agents-relay')
             return;
-        if (event.timestamp && new Date(event.timestamp).getTime() < live.launchBarrier)
+        const live = this.live.get(event.task_id);
+        if (live && event.job_id === live.jobId) {
+            if (event.timestamp && new Date(event.timestamp).getTime() < live.launchBarrier)
+                return;
+            live.workerStarted = true;
+            return;
+        }
+        const job = await this.store.load(event.job_id);
+        const task = job.tasks.find(item => item.id === event.task_id);
+        if (!task || task.state !== 'FAILED' || !this.isRecoverableWatchdogFailure(task))
             return;
-        live.workerStarted = true;
+        if (event.timestamp && new Date(event.timestamp).getTime() < new Date(task.updatedAt).getTime())
+            return;
+        transitionTask(task, 'RUNNING');
+        task.failureReason = undefined;
+        task.error = null;
+        task.updatedAt = event.timestamp || new Date().toISOString();
+        await this.store.saveTask(task);
+        this.detach(this.reconcile(job.id), job.id, task.id, 'late worker-start reconciliation');
+    }
+    isRecoverableWatchdogFailure(task) {
+        if (['worker_start_timeout', 'terminal_event_timeout', 'worker_exit_before_start', 'worker_exit_without_terminal_event'].includes(task.failureReason ?? ''))
+            return true;
+        const error = task.error ?? '';
+        return error.includes('worker_start_timeout')
+            || error.includes('timed out waiting for the mandatory terminal worker event')
+            || error.includes('exited before publishing task.started')
+            || error.includes('exited after task.started without publishing a terminal task event');
+    }
+    isWorkerOwnedEvent(event) {
+        const sourceAgent = typeof event.source?.agent === 'string' ? event.source.agent : '';
+        const sourceComponent = typeof event.source?.component === 'string' ? event.source.component : '';
+        return sourceAgent !== 'relay' && sourceComponent !== 'agents-relay';
     }
     async failLaunch(jobId, taskId, executionId, message, phase = 'launch') {
         const claim = executionId ?? `${jobId}:${taskId}`;
@@ -592,7 +619,16 @@ export class Reconciler {
     async applyTerminalEvent(event) {
         const job = await this.store.load(event.job_id);
         const task = job.tasks.find(item => item.id === event.task_id);
-        if (!task || !['codex', 'chatgpt'].includes(task.adapter) || task.state !== 'RUNNING')
+        if (!task || !['codex', 'chatgpt'].includes(task.adapter))
+            return;
+        if (task.state === 'FAILED' && this.isRecoverableWatchdogFailure(task) && this.isWorkerOwnedEvent(event)) {
+            if (event.timestamp && new Date(event.timestamp).getTime() < new Date(task.updatedAt).getTime())
+                return;
+            transitionTask(task, 'RUNNING');
+            task.failureReason = undefined;
+            task.error = null;
+        }
+        if (task.state !== 'RUNNING')
             return;
         const terminalWaiter = this.terminalWaiters.get(task.id);
         if (terminalWaiter && (!event.timestamp || new Date(event.timestamp).getTime() < terminalWaiter.launchBarrier))
@@ -606,12 +642,14 @@ export class Reconciler {
         if (event.type === 'task.completed') {
             task.result = { summary: event.message || `Task ${task.id} completed`, data: event.data };
             task.error = null;
+            task.failureReason = undefined;
             transitionTask(task, 'SUCCEEDED');
             await this.store.saveTask(task);
             await this.deliverContinuation(job, task);
         }
         else if (event.type === 'task.failed') {
             task.error = event.message || `Task ${task.id} failed`;
+            task.failureReason = typeof event.data?.reason === 'string' ? event.data.reason : undefined;
             transitionTask(task, 'FAILED');
             await this.store.saveTask(task);
         }

package/dist/types.js

@@ -1,8 +1,9 @@
-export const STORY_SIZE_TIMEOUT_MS = { S: 120000, M: 300000, L: 900000 };
+export const STORY_SIZE_TIMEOUT_MS = { S: 300000, M: 900000, L: 2700000 };
 export function storySizeTimeoutMs(size) { return STORY_SIZE_TIMEOUT_MS[size]; }
 export function taskOverallTimeoutMs(size, reasoning) { return storySizeTimeoutMs(size) * (reasoning?.toLowerCase() === 'high' ? 2 : 1); }
+export function chatGptStartAckTimeoutMs(overallTimeoutMs) { return Math.min(600000, Math.max(120000, Math.floor(overallTimeoutMs / 3))); }
 const jobTransitions = { OPEN: ['RUNNING', 'WAITING', 'BLOCKED', 'COMPLETED', 'CANCELLED'], RUNNING: ['OPEN', 'WAITING', 'BLOCKED', 'COMPLETED', 'FAILED', 'CANCELLED'], WAITING: ['RUNNING', 'BLOCKED', 'COMPLETED', 'CANCELLED'], BLOCKED: ['RUNNING', 'CANCELLED'], COMPLETED: ['RUNNING', 'CANCELLED'], FAILED: ['RUNNING', 'CANCELLED'], CANCELLED: ['RUNNING'] };
-const taskTransitions = { QUEUED: ['READY', 'BLOCKED', 'CANCELLED'], READY: ['RUNNING', 'BLOCKED', 'FAILED', 'CANCELLED'], RUNNING: ['WAITING', 'BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED', 'READY'], WAITING: ['READY', 'BLOCKED', 'CANCELLED'], BLOCKED: ['READY', 'CANCELLED'], SUCCEEDED: [], FAILED: ['READY', 'CANCELLED'], CANCELLED: [] };
+const taskTransitions = { QUEUED: ['READY', 'BLOCKED', 'CANCELLED'], READY: ['RUNNING', 'BLOCKED', 'FAILED', 'CANCELLED'], RUNNING: ['WAITING', 'BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED', 'READY'], WAITING: ['READY', 'BLOCKED', 'CANCELLED'], BLOCKED: ['READY', 'CANCELLED'], SUCCEEDED: [], FAILED: ['READY', 'RUNNING', 'CANCELLED'], CANCELLED: [] };
 export function assertJobTransition(from, to) { if (from !== to && !jobTransitions[from].includes(to))
     throw new Error(`Invalid job transition ${from} -> ${to}`); }
 export function assertTaskTransition(from, to) { if (from !== to && !taskTransitions[from].includes(to))

package/package.json

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

package/skills/agents-relay/SKILL.md

@@ -7,6 +7,10 @@ description: Create and operate durable asynchronous agent jobs through GitHub P
 
 Use Agents Relay when an orchestrator needs durable delegated work that survives the current process.
 
+## Required shared contract
+
+Before creating, planning, reviewing, or managing a job/task, read and follow `contracts/task-job-contract.md`. This is the canonical producer/runtime protocol for story size, lifecycle events, review, and auto-merge.
+
 ## Core task contract
 
 A managed child task is always a descriptive unit of work. It says what an agent must accomplish; it is never a shell command.

package/skills/agents-relay/agents/planner.agent.md

@@ -2,6 +2,8 @@
 
 You are the default objective planner for Agents Relay autonomous jobs.
 
+Before producing tasks, read and follow `../contracts/task-job-contract.md`.
+
 Inspect the durable objective and task tree, then decide whether the objective is satisfied or which descriptive agent tasks should run next.
 
 ## Rules
@@ -12,21 +14,11 @@ Inspect the durable objective and task tree, then decide whether the objective i
 - Preserve parent/subtask causality and stable IDs.
 - A child task describes what an agent must accomplish. Never emit a shell command as a worker task.
 - Every child task must use adapter `codex` or `chatgpt`.
-- Every child task must declare exactly one output:
-  - `{"kind":"task_pr"}`, or
-  - `{"kind":"file","path":"..."}`.
+- Every child task must declare exactly one output: `task_pr` or `file`.
 - Include routing metadata for every model-backed child task.
-- Do not call an execution agent "codex"; agent identity describes responsibility, while the adapter describes runtime.
-- If a child task includes `priority`, emit the canonical string `P0`, `P1`, `P2`, or `P3` exactly. Do not emit numeric priorities, lowercase aliases, or labels such as `high`/`medium`/`low`.
+- Every child task must include `storySize` according to the shared Task / Job Contract. Use `M` when uncertain.
 - Return no prose outside the JSON result.
 
 ## Output
 
-Return exactly one JSON object with:
-- objective_status: "in_progress" or "satisfied"
-- assessment: a short evidence-based assessment
-- next_tasks: an array of typed task objects
-
-Each next task contains: id, input, adapter, output, routing, and may also contain priority, projectName, agentName, dependencies, capabilities, maxAttempts, and timeoutMs.
-
-When the objective is satisfied, next_tasks must be empty.
+Return exactly one JSON object with `objective_status`, `assessment`, and `next_tasks`. Each next task contains id, input, adapter, output, routing, storySize, and may also contain priority, projectName, agentName, dependencies, capabilities, maxAttempts, and timeoutMs. When the objective is satisfied, next_tasks must be empty.

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

@@ -0,0 +1,32 @@
+# Agents Relay Task / Job Contract
+
+This contract is the shared protocol for every component that creates, schedules, reviews, or executes Agents Relay jobs and tasks.
+
+## Task producers
+
+Any task producer — orchestrator, planner, or nested task-producing agent — must follow this contract.
+Task producers choose semantic task properties such as objective, dependencies, adapter/routing, priority, and `storySize`. They do not normally choose raw timeout milliseconds.
+
+## Story size
+
+Every worker task has one of three story sizes:
+
+- `S`: about 5 minutes of normal-reasoning execution.
+- `M`: about 15 minutes of normal-reasoning execution. This is the default when size is absent or uncertain.
+- `L`: about 45 minutes of normal-reasoning execution.
+
+Relay derives the overall execution timeout from `storySize`. If `routing.reasoning` is `high`, Relay doubles the overall execution timeout. Other reasoning levels do not change it.
+
+Raw `timeoutMs` is a compatibility/debug/hotfix override, not the normal task-production interface.
+
+## 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.
+
+## Job and review lifecycle
+
+A normal task never merges a PR. After all non-superseded work gates pass, Relay creates a SHA-bound final review task. The reviewer emits exactly one of `review.approved`, `review.changes_required`, or `review.blocked`. When `autoMerge` is enabled (default), Relay merges only after `review.approved`, pinned to the exact reviewed head SHA. A new task or new PR head makes earlier final-review evidence stale and requires a fresh review.
+
+## Fixed and autonomous jobs
+
+`fixed` jobs execute the orchestrator-provided task set and then proceed to final review. `autonomous` jobs may ask the planner for additional task batches. Planner-produced tasks must obey this same contract, including explicit `storySize`.