agents-relay 1.0.27 → 1.0.29

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, timeout derivation, 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

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { randomUUID } from 'node:crypto';
 import { dashboardManagedJobs, InMemoryStore, GitHubStore, resolvePullRequest, listManagedGitHubJobs } from './store.js';
 import { githubAuthContext } from './github-auth.js';
+import { taskOverallTimeoutMs } from './types.js';
 import { Reconciler } from './reconciler.js';
 import { CodexAdapter, ChatGptAdapter } from './adapters.js';
 import { CodexThreadContinuation, CommandContinuation, WebhookContinuation } from './continuation.js';
@@ -90,7 +91,7 @@ Actions:
     'task update': `Update mutable durable task fields in place.
 
 Required: --task-id ID and the normal job storage options.
-Mutable while not RUNNING/SUCCEEDED/CANCELLED: --adapter, --priority, --input, --project, --agent, --parent, --deps, --capabilities, --timeout, --max-attempts, --provider, --model, --profile, --reasoning, --cwd, --chatgpt-project, --chatgpt-tab-close-policy.
+Mutable while not RUNNING/SUCCEEDED/CANCELLED: --adapter, --priority, --story-size, --input, --project, --agent, --parent, --deps, --capabilities, --timeout, --max-attempts, --provider, --model, --profile, --reasoning, --cwd, --chatgpt-project, --chatgpt-tab-close-policy.
 Use --clear-routing to remove routing metadata. A model update requires --model; provider defaults to the existing provider or openai.
 
 Example:
@@ -98,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."`,
@@ -224,6 +225,8 @@ catch (error) {
 } }
 function priority(args, fallback = 'P2') { const value = arg(args, '--priority', fallback); if (!['P0', 'P1', 'P2', 'P3'].includes(value))
     throw new Error('--priority must be P0, P1, P2, or P3'); return value; }
+function storySize(args, fallback = 'M') { const value = arg(args, '--story-size', fallback).toUpperCase(); if (!['S', 'M', 'L'].includes(value))
+    throw new Error('--story-size must be S, M, or L'); return value; }
 export function executionMode(args, fallback = 'fixed') { const value = arg(args, '--mode', arg(args, '--execution-mode', fallback)); if (value !== 'fixed' && value !== 'autonomous')
     throw new Error('--mode must be fixed or autonomous'); return value; }
 export function chatGptTabClosePolicy(args) {
@@ -285,10 +288,13 @@ function workerTaskFromArgs(job, args, now, requireInput = false) {
         throw new Error('--output file requires --output-path');
     const routing = { provider: arg(args, '--provider', 'openai'), model, profile: arg(args, '--profile') || undefined, reasoning: arg(args, '--reasoning') || undefined, cwd: arg(args, '--cwd') || undefined, projectId: arg(args, '--chatgpt-project') || undefined, decidedBy: 'cli', decidedAt: now };
     const closePolicy = hasArg(args, '--chatgpt-tab-close-policy') ? chatGptTabClosePolicy(args) : undefined;
+    const size = storySize(args);
+    const timeoutMs = hasArg(args, '--timeout') ? integerArg(args, '--timeout', taskOverallTimeoutMs(size, routing.reasoning)) : taskOverallTimeoutMs(size, routing.reasoning);
     return {
         jobId: job.id,
         id: arg(args, '--task-id', 'initial'),
         priority: priority(args, job.priority ?? 'P2'),
+        storySize: size,
         projectName: arg(args, '--project') || undefined,
         agentName: arg(args, '--agent') || undefined,
         parentTaskId: arg(args, '--parent') || null,
@@ -310,7 +316,7 @@ function workerTaskFromArgs(job, args, now, requireInput = false) {
         threadId: null,
         result: null,
         error: null,
-        timeoutMs: Number(arg(args, '--timeout', '300000')),
+        timeoutMs,
         createdAt: now,
         updatedAt: now
     };
@@ -335,6 +341,11 @@ async function runTaskCommand(action, args) {
     }
     if (hasArg(args, '--priority'))
         task.priority = priority(args, task.priority ?? job.priority ?? 'P2');
+    if (hasArg(args, '--story-size')) {
+        task.storySize = storySize(args, task.storySize ?? 'M');
+        if (!hasArg(args, '--timeout'))
+            task.timeoutMs = taskOverallTimeoutMs(task.storySize, task.routing?.reasoning);
+    }
     if (hasArg(args, '--input'))
         task.input = arg(args, '--input');
     if (hasArg(args, '--project'))
@@ -371,6 +382,8 @@ async function runTaskCommand(action, args) {
             decidedBy: 'cli:update',
             decidedAt: new Date().toISOString()
         };
+        if (hasArg(args, '--reasoning') && !hasArg(args, '--timeout'))
+            task.timeoutMs = taskOverallTimeoutMs(task.storySize ?? 'M', task.routing.reasoning);
     }
     task.updatedAt = new Date().toISOString();
     await store.saveTask(task);
@@ -427,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

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
+import { taskOverallTimeoutMs } from './types.js';
 function record(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new Error('Planner result must be an object');
@@ -83,17 +84,22 @@ export function parsePlannerResult(value) {
         if (output.kind === 'file' && (typeof output.path !== 'string' || output.path.length === 0))
             throw new Error(`Planner next_tasks[${index}].output.path is required for file output`);
         const priority = task.priority === undefined ? undefined : normalizePlannerPriority(task.priority, `next_tasks[${index}].priority`);
+        const sizeValue = task.storySize === undefined ? 'M' : String(task.storySize).toUpperCase();
+        if (!['S', 'M', 'L'].includes(sizeValue))
+            throw new Error('Planner next_tasks[' + index + '].storySize must be S, M, or L');
+        const storySize = sizeValue;
         const maxAttempts = task.maxAttempts === undefined ? 3 : task.maxAttempts;
-        const timeoutMs = task.timeoutMs === undefined ? 300000 : task.timeoutMs;
+        const route = routing(task.routing, 'next_tasks[' + index + '].routing');
+        const timeoutMs = task.timeoutMs === undefined ? taskOverallTimeoutMs(storySize, route?.reasoning) : task.timeoutMs;
         if (typeof maxAttempts !== 'number' || !Number.isInteger(maxAttempts) || maxAttempts < 1)
             throw new Error(`Planner next_tasks[${index}].maxAttempts is invalid`);
         if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs < 0)
             throw new Error(`Planner next_tasks[${index}].timeoutMs is invalid`);
         return {
-            id, input: task.input, priority,
+            id, input: task.input, priority, storySize,
             projectName: optionalString(task.projectName, 'projectName'), agentName: optionalString(task.agentName, 'agentName'),
             dependencies: stringArray(task.dependencies, 'dependencies'), capabilities: stringArray(task.capabilities, 'capabilities'),
-            adapter: adapter, output: output, routing: routing(task.routing, `next_tasks[${index}].routing`),
+            adapter: adapter, output: output, routing: route,
             continuation: task.continuation, maxAttempts, timeoutMs
         };
     });
@@ -134,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);
@@ -156,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,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { storySizeTimeoutMs, taskOverallTimeoutMs, chatGptStartAckTimeoutMs } from './types.js';
 import { schedule, transitionTask } from './scheduler.js';
 import { LaunchFailure, StartAckTimeout } from './adapters.js';
 import { eventFor } from './events.js';
@@ -203,7 +204,7 @@ export class Reconciler {
             return;
         const id = `final-review-${headSha.slice(0, 12)}`;
         const now = new Date().toISOString();
-        const task = { jobId: job.id, id, kind: 'work', priority: job.priority, projectName: job.title, agentName: 'reviewer', parentTaskId: null, dependencies: job.tasks.filter(item => item.agentName !== 'reviewer' && !this.isSupersededTask(item)).map(item => item.id), capabilities: ['review'], adapter: this.options.reviewer?.adapter ?? 'codex', input: `Review PR #${job.prNumber} at head SHA ${headSha}. Objective: ${job.objective ?? job.description ?? job.title}. First publish task.started as the worker start acknowledgement with data.worker_owned=true, then verify the deterministic pre-review gates have passed and inspect the completed work. Emit review.started, then exactly one of review.approved, review.changes_required, or review.blocked with data.review.headSha set to ${headSha}. Do not modify code. When auto-merge is enabled, Relay will merge this exact reviewed head after review.approved.`, output: { kind: 'task_pr' }, routing: this.options.reviewer?.routing, continuation: null, continuationDeliveredAt: null, reviewHeadSha: headSha, state: 'QUEUED', attempt: 0, maxAttempts: this.options.reviewer?.maxAttempts ?? 2, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: this.options.reviewer?.timeoutMs ?? 300000, createdAt: now, updatedAt: now };
+        const task = { jobId: job.id, id, kind: 'work', priority: job.priority, storySize: 'M', projectName: job.title, agentName: 'reviewer', parentTaskId: null, dependencies: job.tasks.filter(item => item.agentName !== 'reviewer' && !this.isSupersededTask(item)).map(item => item.id), capabilities: ['review'], adapter: this.options.reviewer?.adapter ?? 'codex', input: `Review PR #${job.prNumber} at head SHA ${headSha}. Objective: ${job.objective ?? job.description ?? job.title}. First publish task.started as the worker start acknowledgement with data.worker_owned=true, then verify the deterministic pre-review gates have passed and inspect the completed work. Emit review.started, then exactly one of review.approved, review.changes_required, or review.blocked with data.review.headSha set to ${headSha}. Do not modify code. When auto-merge is enabled, Relay will merge this exact reviewed head after review.approved.`, output: { kind: 'task_pr' }, routing: this.options.reviewer?.routing, continuation: null, continuationDeliveredAt: null, reviewHeadSha: headSha, state: 'QUEUED', attempt: 0, maxAttempts: this.options.reviewer?.maxAttempts ?? 2, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: this.options.reviewer?.timeoutMs ?? storySizeTimeoutMs('M'), createdAt: now, updatedAt: now };
         await this.store.appendTask(task);
         job.review = { outcome: 'pending', headSha, taskId: id, evidence: null, updatedAt: now };
         job.state = 'RUNNING';
@@ -301,7 +302,7 @@ export class Reconciler {
             id = `planner-${number}`;
         }
         const now = new Date().toISOString();
-        const task = { jobId: job.id, id, kind: 'planner', agentName: 'planner', parentTaskId: latest?.id ?? null, dependencies: [], capabilities: ['planner'], adapter: 'orchestrator', input: plannerInput({ job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: latest?.id ?? null }), continuation: null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: this.options.plannerTimeoutMs ?? 300000, createdAt: now, updatedAt: now };
+        const task = { jobId: job.id, id, kind: 'planner', storySize: 'M', agentName: 'planner', parentTaskId: latest?.id ?? null, dependencies: [], capabilities: ['planner'], adapter: 'orchestrator', input: plannerInput({ job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: latest?.id ?? null }), continuation: null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M'), createdAt: now, updatedAt: now };
         await this.store.appendTask(task);
         await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.created', 'queued', `Planner task ${task.id} created`, 'orchestrator'));
         return this.store.load(job.id);
@@ -342,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)
@@ -496,7 +497,7 @@ export class Reconciler {
     }
     plannerChild(job, planner, spec) {
         const now = new Date().toISOString();
-        return { jobId: job.id, id: spec.id, kind: 'work', priority: spec.priority ?? job.priority, projectName: spec.projectName, agentName: spec.agentName, parentTaskId: planner.id, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], adapter: spec.adapter, input: spec.input, output: spec.output, routing: spec.routing, continuation: spec.continuation ?? null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: spec.maxAttempts ?? 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: spec.timeoutMs ?? 300000, createdAt: now, updatedAt: now };
+        return { jobId: job.id, id: spec.id, kind: 'work', priority: spec.priority ?? job.priority, storySize: spec.storySize ?? 'M', projectName: spec.projectName, agentName: spec.agentName, parentTaskId: planner.id, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], adapter: spec.adapter, input: spec.input, output: spec.output, routing: spec.routing, continuation: spec.continuation ?? null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: spec.maxAttempts ?? 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: spec.timeoutMs ?? taskOverallTimeoutMs(spec.storySize ?? 'M', spec.routing?.reasoning), createdAt: now, updatedAt: now };
     }
     clearExecution(taskId, executionId) {
         const live = this.live.get(taskId);
@@ -697,5 +698,5 @@ export class Reconciler {
     } }
 }
 function samePlannerChildDefinition(left, right) {
-    return JSON.stringify({ id: left.id, input: left.input, output: left.output, priority: left.priority, projectName: left.projectName, agentName: left.agentName, dependencies: left.dependencies, capabilities: left.capabilities, adapter: left.adapter, routing: left.routing, continuation: left.continuation ?? null, maxAttempts: left.maxAttempts, timeoutMs: left.timeoutMs }) === JSON.stringify({ id: right.id, input: right.input, output: right.output, priority: right.priority, projectName: right.projectName, agentName: right.agentName, dependencies: right.dependencies, capabilities: right.capabilities, adapter: right.adapter, routing: right.routing, continuation: right.continuation ?? null, maxAttempts: right.maxAttempts, timeoutMs: right.timeoutMs });
+    return JSON.stringify({ id: left.id, input: left.input, output: left.output, priority: left.priority, storySize: left.storySize ?? 'M', projectName: left.projectName, agentName: left.agentName, dependencies: left.dependencies, capabilities: left.capabilities, adapter: left.adapter, routing: left.routing, continuation: left.continuation ?? null, maxAttempts: left.maxAttempts, timeoutMs: left.timeoutMs }) === JSON.stringify({ id: right.id, input: right.input, output: right.output, priority: right.priority, storySize: right.storySize ?? 'M', projectName: right.projectName, agentName: right.agentName, dependencies: right.dependencies, capabilities: right.capabilities, adapter: right.adapter, routing: right.routing, continuation: right.continuation ?? null, maxAttempts: right.maxAttempts, timeoutMs: right.timeoutMs });
 }

package/dist/store.js

@@ -81,7 +81,7 @@ function immutableTaskDefinition(task) {
         reasoning: task.routing.reasoning, cwd: task.routing.cwd, projectId: task.routing.projectId
     } : undefined;
     return {
-        jobId: task.jobId, id: task.id, priority: task.priority, projectName: task.projectName, agentName: task.agentName,
+        jobId: task.jobId, id: task.id, priority: task.priority, storySize: task.storySize ?? 'M', projectName: task.projectName, agentName: task.agentName,
         kind: task.kind ?? 'work', parentTaskId: task.parentTaskId, dependencies: task.dependencies, capabilities: task.capabilities, adapter: task.adapter,
         input: task.input, output: task.output, routing, chatgptTabClosePolicy: task.chatgptTabClosePolicy ?? 'after-start', continuation: task.continuation ?? null, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs
     };

package/dist/types.js

@@ -1,3 +1,7 @@
+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(300000, Math.max(60000, 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: [] };
 export function assertJobTransition(from, to) { if (from !== to && !jobTransitions[from].includes(to))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "1.0.27",
+  "version": "1.0.29",
   "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,36 @@
+# 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.
+
+For ChatGPT Browser Worker tasks, Relay derives start-ack timeout from the effective overall timeout:
+
+`startAckTimeout = clamp(overallTimeout / 3, 1 minute, 5 minutes)`
+
+This applies equally to normal ChatGPT tasks and reviewer tasks. 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`.