agents-relay 1.0.72 → 1.0.74

package/README.md

@@ -1,6 +1,6 @@
 # Agents Relay
 
-Agents Relay is a generic TypeScript runtime for durable asynchronous agent jobs coordinated through GitHub pull requests. GitHub PR comments store durable workflow state; correlated terminal events are authoritative for model-backed task lifecycle transitions.
+Agents Relay is a generic TypeScript runtime for durable asynchronous agent jobs coordinated through GitHub pull requests. The PR body stores the durable Job marker plus human-readable Job objective, while PR comments store durable Task and other append-friendly records; correlated terminal events are authoritative for model-backed task lifecycle transitions.
 
 ## Quick start
 
@@ -53,7 +53,7 @@ Lifecycle transition authority lives in the directly renderable canonical source
 
 Graph-engine rollout is confidence-gated with `AGENTS_RELAY_WORKFLOW_MODE=legacy|shadow|graph` (default `legacy`). `shadow` keeps legacy authoritative while comparing the Mermaid decision and exposing `{mode,matches,mismatches}` at `/api/workflow-rollout`; `graph` is explicit opt-in until the shadow cutover gate is approved.
 
-Job objectives and Task inputs are Markdown. Prefer `--objective-file` / `--input-file` (use `-` for stdin) for durable long-form context; inline `--objective` / `--input` remain for short/simple text and are mutually exclusive with the file variants. When a diagram materially clarifies the work, put Mermaid first and then Markdown detail. A newly created Job must capture enough context to finish independently of the originating chat; its objective becomes the default PR body and objective updates keep the PR body synchronized.
+Job objectives and Task inputs are Markdown. Prefer `--objective-file` / `--input-file` (use `-` for stdin) for durable long-form context; inline `--objective` / `--input` remain for short/simple text and are mutually exclusive with the file variants. When a diagram materially clarifies the work, put Mermaid first and then Markdown detail. A newly created Job must capture enough context to finish independently of the originating chat. Its PR body contains exactly one hidden `agents-relay:job:v1` metadata marker followed by the objective Markdown; there is no separate Job comment duplicating the objective. Objective and Job metadata updates rewrite that same PR body. Legacy Job-comment markers remain readable and are migrated into the PR body on the next Job save.
 
 Jobs default to `fixed`. `job create` persists only the durable job and never
 creates executable tasks. The top-level orchestrator decides whether the user's
@@ -141,7 +141,7 @@ reconcile leases and launches ready tasks without waiting inside the runtime sch
 
 For automation, Agents Relay can use GitHub App installation authentication via `AGENTS_RELAY_GITHUB_APP_ID`, `AGENTS_RELAY_GITHUB_APP_INSTALLATION_ID`, and `AGENTS_RELAY_GITHUB_APP_PRIVATE_KEY_FILE` (or matching CLI flags). Webhook mode is cache-first: targeted webhook reconciliation is primary, dashboard auto-refresh reads cached job state, and the broad watchdog drops to a 30-minute fallback. See [docs/github-app-rate-limit.md](docs/github-app-rate-limit.md).
 
-V1 assumes one active runner/daemon per job. Use a distributed atomic lease before running multiple reconcilers. Do not put secrets, credentials, private prompts, or large private payloads in PR marker comments; store only summaries and artifact references.
+V1 assumes one active runner/daemon per job. Use a distributed atomic lease before running multiple reconcilers. Do not put secrets, credentials, private prompts, or large private payloads in the PR-body Job marker or PR-comment Task markers; store only summaries and artifact references.
 
 Codex/model-backed tasks require --provider and --model (or equivalent routing metadata) before launch. See [docs/architecture.md](docs/architecture.md) and [skills/agents-relay/SKILL.md](skills/agents-relay/SKILL.md).
 
@@ -176,4 +176,4 @@ 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`.
 
-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. Managed jobs also retain the GitHub PR body as the job description for dashboard display.
+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/agent-graph.js

@@ -0,0 +1,74 @@
+import { agentContractPrompt } from './execution-context.js';
+const ID = '[A-Za-z_][A-Za-z0-9_.-]*';
+const EDGE = new RegExp(`^(${ID})(?:\\[agent:(${ID})\\])?\\s*-->\\s*(${ID})(?:\\[agent:(${ID})\\])?$`);
+const NODE = new RegExp(`^(${ID})\\[agent:(${ID})\\]$`);
+export function parseAgentGraph(source) {
+    const lines = source.split(/\r?\n/);
+    let header = false;
+    const agents = new Map();
+    const edges = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index].trim();
+        if (!line || line.startsWith('%%'))
+            continue;
+        if (!header) {
+            if (!/^flowchart\s+(?:TD|TB|LR|RL)$/.test(line))
+                throw new Error(`Agent Graph must start with Mermaid flowchart TD/TB/LR/RL (line ${index + 1})`);
+            header = true;
+            continue;
+        }
+        const edge = line.match(EDGE);
+        if (edge) {
+            const [, from, fromAgent, to, toAgent] = edge;
+            agents.set(from, fromAgent || agents.get(from) || from);
+            agents.set(to, toAgent || agents.get(to) || to);
+            edges.push({ from, to });
+            continue;
+        }
+        const node = line.match(NODE);
+        if (node) {
+            agents.set(node[1], node[2]);
+            continue;
+        }
+        throw new Error(`Unsupported Agent Graph syntax at line ${index + 1}: ${line}`);
+    }
+    if (!header)
+        throw new Error('Agent Graph is empty');
+    if (agents.size === 0)
+        throw new Error('Agent Graph requires at least one agent node');
+    const incoming = new Map([...agents.keys()].map(id => [id, 0]));
+    const outgoing = new Map([...agents.keys()].map(id => [id, []]));
+    for (const edge of edges) {
+        if (edge.from === edge.to)
+            throw new Error(`Agent Graph self-cycle at ${edge.from}`);
+        incoming.set(edge.to, (incoming.get(edge.to) ?? 0) + 1);
+        outgoing.get(edge.from)?.push(edge.to);
+    }
+    const remaining = new Map(incoming);
+    const waves = [];
+    let ready = [...remaining.entries()].filter(([, degree]) => degree === 0).map(([id]) => id).sort();
+    let visited = 0;
+    while (ready.length) {
+        waves.push(ready);
+        visited += ready.length;
+        const next = new Set();
+        for (const id of ready) {
+            for (const target of outgoing.get(id) ?? []) {
+                const degree = (remaining.get(target) ?? 0) - 1;
+                remaining.set(target, degree);
+                if (degree === 0)
+                    next.add(target);
+            }
+        }
+        ready = [...next].sort();
+    }
+    if (visited !== agents.size)
+        throw new Error('Agent Graph contains a cycle');
+    return { source, nodes: [...agents].map(([id, agent]) => ({ id, agent })), edges, waves };
+}
+export async function agentGraphPrompt(context, source) {
+    const graph = parseAgentGraph(source);
+    const contracts = await Promise.all(graph.nodes.map(async (node) => ({ node, prompt: await agentContractPrompt(context, node.agent) })));
+    const incoming = new Map(graph.nodes.map(node => [node.id, graph.edges.filter(edge => edge.to === node.id).map(edge => edge.from)]));
+    return `[Task Agent Graph]\n${source.trim()}\n\nExecution waves: ${graph.waves.map((wave, index) => `${index + 1}:${wave.join(',')}`).join(' | ')}\n\nExecute this graph inside the current durable Task. Nodes are reasoning roles, NOT durable child Tasks. Preserve the original Job/Task context for every node. Nodes in the same wave are independent: evaluate each from the same original context without using sibling prose. For each later node, provide the original context plus structured outputs only from its declared predecessors. Do not emit outer task.started or task terminal events per node; the current durable Task owns exactly one start and one terminal event.\n\n${contracts.map(({ node, prompt }) => `[Node ${node.id}; predecessors=${(incoming.get(node.id) ?? []).join(',') || 'none'}]\n${prompt}`).join('\n\n')}`;
+}

package/dist/cli.js

@@ -110,7 +110,7 @@ Actions:
     'task create': `Create one durable Task under an existing Job.
 
 Required: normal Job storage options plus --input-file PATH|- (preferred) or --input MARKDOWN, and --output task-pr|file. --input and --input-file are mutually exclusive. Codex/ChatGPT tasks also require --model MODEL.
-Common: --task-id ID, --adapter codex|chatgpt|orchestrator, --priority P0|P1|P2|P3, --story-size S|M|L, --deps a,b, --parent ID, --draft.\nTasks with dependencies start DRAFT; tasks without dependencies start QUEUED unless --draft is given.
+Common: --task-id ID, --adapter codex|chatgpt|orchestrator, --priority P0|P1|P2|P3, --story-size S|M|L, --agent NAME, --agent-graph-file PATH|-, --deps a,b, --parent ID, --draft.\nTasks with dependencies start DRAFT; tasks without dependencies start QUEUED unless --draft is given.
 Directly-created Tasks are not wrapped in a synthetic Plan. Planner-generated Tasks are created internally by Relay from planner output.
 
 Example:
@@ -118,7 +118,7 @@ Example:
     '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, --story-size, --input-file PATH|- or --input MARKDOWN, --project, --agent, --parent, --deps, --capabilities, --timeout, --max-attempts, --provider, --model, --profile, --reasoning, --cwd, --chatgpt-project, --chatgpt-tab-close-policy, --draft, --queue.
+Mutable while not RUNNING/SUCCEEDED/CANCELLED: --adapter, --priority, --story-size, --input-file PATH|- or --input MARKDOWN, --project, --agent, --agent-graph-file PATH|-, --parent, --deps, --capabilities, --timeout, --max-attempts, --provider, --model, --profile, --reasoning, --cwd, --chatgpt-project, --chatgpt-tab-close-policy, --draft, --queue.
 Use --clear-routing to remove routing metadata.
 
 Example:
@@ -352,6 +352,7 @@ async function workerTaskFromArgs(job, args, now) {
     const outputKind = arg(args, '--output');
     const outputPath = arg(args, '--output-path');
     const input = await textOption(args, '--input', '--input-file');
+    const agentGraph = hasArg(args, '--agent-graph') || hasArg(args, '--agent-graph-file') ? await textOption(args, '--agent-graph', '--agent-graph-file') : undefined;
     if (!input.trim())
         throw new Error('task create requires --input-file PATH|- or --input MARKDOWN');
     if (!['codex', 'chatgpt', 'orchestrator'].includes(adapter))
@@ -374,6 +375,7 @@ async function workerTaskFromArgs(job, args, now) {
         storySize: size,
         projectName: arg(args, '--project') || undefined,
         agentName: arg(args, '--agent') || undefined,
+        agentGraph,
         parentTaskId: arg(args, '--parent') || null,
         dependencies,
         capabilities: arg(args, '--capabilities').split(',').filter(Boolean),
@@ -474,6 +476,8 @@ async function runTaskCommand(action, args) {
         task.projectName = arg(args, '--project') || undefined;
     if (hasArg(args, '--agent'))
         task.agentName = arg(args, '--agent') || undefined;
+    if (hasArg(args, '--agent-graph') || hasArg(args, '--agent-graph-file'))
+        task.agentGraph = await textOption(args, '--agent-graph', '--agent-graph-file');
     if (hasArg(args, '--parent'))
         task.parentTaskId = arg(args, '--parent') || null;
     if (hasArg(args, '--deps'))
@@ -635,7 +639,6 @@ async function runJobCommand(action, args) {
         if (!objective.trim())
             throw new Error('Job objective cannot be empty');
         job.objective = objective;
-        await store.updatePullRequestBody?.(objective);
     }
     if (hasArg(args, '--priority'))
         job.priority = priority(args, job.priority ?? 'P2');

package/dist/dashboard.js

@@ -158,7 +158,7 @@ export const dashboardHtml = `<!doctype html>
 </header>
 <main>
   <section id="jobs-view" role="tabpanel" aria-labelledby="jobs-tab" class="panel jobs-panel">
-    <div class="panel-head"><h2>Jobs</h2><div class="panel-actions"><div class="job-filters"><button id="quick-jobs" class="quick-filter" type="button" aria-pressed="true">JOBS</button><select id="quick-status" class="job-filter" aria-label="Filter jobs by derived status"><option value="">STATUS</option></select><button id="quick-autonomous" class="quick-filter" type="button" aria-pressed="false">AUTONOMOUS</button><button id="quick-draft" class="quick-filter" type="button" aria-pressed="false">DRAFT</button><select id="repo-filter" class="job-filter" aria-label="Filter jobs by repository"><option value="">All repos</option></select></div><button id="jobs-refresh" class="refresh-button" type="button">Refresh</button></div></div>
+    <div class="panel-head"><h2>Jobs</h2><div class="panel-actions"><div class="job-filters"><select id="quick-status" class="job-filter" aria-label="Filter jobs by derived status"><option value="">STATUS</option></select><button id="quick-autonomous" class="quick-filter" type="button" aria-pressed="false">AUTONOMOUS</button><button id="quick-draft" class="quick-filter" type="button" aria-pressed="false">DRAFT</button><select id="repo-filter" class="job-filter" aria-label="Filter jobs by repository"><option value="">All repos</option></select></div><button id="jobs-refresh" class="refresh-button" type="button">Refresh</button></div></div>
     <div class="panel-body" aria-live="polite"><ul id="job-list" class="job-list"><li class="skeleton" aria-hidden="true"></li></ul></div>
   </section>
   <div class="workspace" id="jobs-workspace">
@@ -207,7 +207,6 @@ const jobsWorkspace=document.querySelector('#jobs-workspace');
 const jobList=document.querySelector('#job-list');
 const jobsRefresh=document.querySelector('#jobs-refresh');
 const repoFilter=document.querySelector('#repo-filter');
-const quickJobs=document.querySelector('#quick-jobs');
 const quickStatus=document.querySelector('#quick-status');
 const quickAutonomous=document.querySelector('#quick-autonomous');
 const quickDraft=document.querySelector('#quick-draft');
@@ -263,7 +262,6 @@ function syncFilters(){
   selectedRuntimeStatus=statuses.includes(previousStatus)?previousStatus:'';
   if(quickMode==='status'&&!selectedRuntimeStatus)quickMode='jobs';
   quickStatus.value=quickMode==='status'?selectedRuntimeStatus:'';
-  quickJobs.setAttribute('aria-pressed',String(quickMode==='jobs'));
   quickAutonomous.setAttribute('aria-pressed',String(quickMode==='autonomous'));
   quickDraft.setAttribute('aria-pressed',String(quickMode==='draft'));
 }
@@ -307,7 +305,6 @@ jobsTab.addEventListener('click',()=>{location.hash=selectedJob?'#/jobs/'+encode
 jobsRefresh.addEventListener('click',()=>void refresh(true));
 eventsAllTasks.addEventListener('click',()=>{eventTaskId=null;clearEvents();renderEventScope();void loadEventHistory();});
 repoFilter.addEventListener('change',()=>{selectedRepo=repoFilter.value;sessionStorage.setItem('agents-relay:repo-filter',selectedRepo);renderJobList();});
-quickJobs.addEventListener('click',()=>setQuickMode('jobs'));
 quickAutonomous.addEventListener('click',()=>setQuickMode('autonomous'));
 quickDraft.addEventListener('click',()=>setQuickMode('draft'));
 quickStatus.addEventListener('change',()=>setQuickMode(quickStatus.value?'status':'jobs',quickStatus.value));

package/dist/execution-context.js

@@ -224,6 +224,31 @@ export async function resolveExecutionContext(projectPath, role, options = {}) {
         delegation: { mode: 'relay-child-task', parentTaskIdRequired: role === 'nested-worker' },
     };
 }
+export async function resolveAgentContract(context, agentName) {
+    const agent = context.agents.find(candidate => candidate.name === agentName);
+    if (!agent)
+        throw new Error(`Agent ${agentName} is not visible in the resolved execution context`);
+    if (!agent.path)
+        throw new Error(`Agent ${agentName} has no readable Markdown contract`);
+    const definition = await readFile(agent.path, 'utf8');
+    if (!definition.trim())
+        throw new Error(`Agent ${agentName} Markdown contract is empty`);
+    return { agent, definition };
+}
+export async function agentContractPrompt(context, agentName) {
+    const { agent, definition } = await resolveAgentContract(context, agentName);
+    return `[Selected task agent contract]
+Agent: ${agent.name}
+Source: ${agent.path ?? agent.source}
+
+The following Markdown is the authoritative behavioral contract for this Task agent.
+Follow it in addition to the shared Job/Task and events-bus contracts. Worker/model routing
+does not change the selected agent identity.
+
+--- BEGIN AGENT CONTRACT ---
+${definition.trim()}
+--- END AGENT CONTRACT ---`;
+}
 export function executionContextPrompt(context) {
     const instructions = context.instructions.map(item => `- ${item.path} [${item.source}]`).join('\n') || '- none';
     const skills = context.skills.map(item => `- ${item.name}: ${item.path} [${item.source}]`).join('\n') || '- none';

package/dist/markers.js

@@ -32,10 +32,18 @@ function contentBeforeDelimiter(body, heading, end) {
         return undefined;
     return body.slice(contentStart, endAt);
 }
+function jobMetadata(job) {
+    const { objective: _objective, description: _description, tasks: _tasks, ...metadata } = job;
+    return metadata;
+}
+export function renderJobBody(job) {
+    const objective = job.objective?.trim() || '_No objective recorded._';
+    return `${marker(JOB_MARKER, jobMetadata(job))}
+${objective}`;
+}
 export function renderJobComment(job) {
     const objective = job.objective?.trim() || '_No objective recorded._';
-    const { objective: _objective, description: _description, tasks: _tasks, ...metadata } = job;
-    return `${marker(JOB_MARKER, metadata)}
+    return `${marker(JOB_MARKER, jobMetadata(job))}
 # Agents Relay job: ${job.title}
 
 - **State:** ${job.state}
@@ -70,7 +78,9 @@ export function parseJob(body) {
     const job = parseMarker(body, JOB_MARKER);
     if (!job)
         return null;
-    const objective = job.objective ?? job.description ?? contentBeforeDelimiter(body, '\n## Objective\n\n', JOB_OBJECTIVE_END) ?? markdownSection(body, '\n## Objective\n');
+    const markerEnd = body.indexOf('-->');
+    const bodyObjective = markerEnd >= 0 ? body.slice(markerEnd + 3).trim() || undefined : undefined;
+    const objective = job.objective ?? job.description ?? contentBeforeDelimiter(body, '\n## Objective\n\n', JOB_OBJECTIVE_END) ?? markdownSection(body, '\n## Objective\n') ?? bodyObjective;
     const parsed = { ...job, objective };
     if (parsed.executionMode === undefined)
         return { ...parsed, executionMode: 'fixed' };

package/dist/planner.js

@@ -9,7 +9,7 @@ export function planningSpec(task) {
         throw new Error(`Initial task ${task.id} requires an output contract`);
     if (!['codex', 'chatgpt', 'orchestrator'].includes(task.adapter))
         throw new Error(`Initial task ${task.id} requires a supported adapter`);
-    return { id: task.id, input: task.input, priority: task.priority, storySize: task.storySize, projectName: task.projectName, agentName: task.agentName, dependencies: task.dependencies, capabilities: task.capabilities, workerRequirements: task.workerRequirements, adapter: task.adapter, output: task.output ?? { kind: 'task_pr' }, routing: task.routing, continuation: task.continuation, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs };
+    return { id: task.id, input: task.input, priority: task.priority, storySize: task.storySize, projectName: task.projectName, agentName: task.agentName, agentGraph: task.agentGraph, dependencies: task.dependencies, capabilities: task.capabilities, workerRequirements: task.workerRequirements, adapter: task.adapter, output: task.output ?? { kind: 'task_pr' }, routing: task.routing, continuation: task.continuation, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs };
 }
 function record(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -126,7 +126,7 @@ export function parsePlannerResult(value) {
             throw new Error(`Planner next_tasks[${index}].timeoutMs is invalid`);
         return {
             id, input: task.input, priority, storySize,
-            projectName: optionalString(task.projectName, 'projectName'), agentName: optionalString(task.agentName, 'agentName'),
+            projectName: optionalString(task.projectName, 'projectName'), agentName: optionalString(task.agentName, 'agentName'), agentGraph: optionalString(task.agentGraph, 'agentGraph'),
             dependencies: stringArray(task.dependencies, 'dependencies'), capabilities: stringArray(task.capabilities, 'capabilities'), workerRequirements: requirements,
             adapter: adapter, output: output, routing: route,
             continuation: task.continuation, maxAttempts, timeoutMs

package/dist/reconciler.js

@@ -5,16 +5,19 @@ import { implementationComplete } from './runtime-status.js';
 import { LaunchFailure, StartAckTimeout } from './adapters.js';
 import { eventFor } from './events.js';
 import { parsePlannerResult, plannerInput } from './planner.js';
-import { executionContextPrompt, resolveExecutionContext } from './execution-context.js';
+import { agentContractPrompt, executionContextPrompt, resolveExecutionContext } from './execution-context.js';
 import { selectReviewer } from './reviewer-routing.js';
+import { agentGraphPrompt } from './agent-graph.js';
 import { selectWorker, usageForProvider, workerCandidates } from './worker-routing.js';
 const PRIORITY_RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
 export function compareTaskPriority(a, b, jobPriority = 'P2') { const ar = PRIORITY_RANK[a.priority ?? jobPriority]; const br = PRIORITY_RANK[b.priority ?? jobPriority]; return ar - br || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
 export function executionEventSource(jobId, taskId, executionId) { return `job/${jobId}/task/${taskId}/execution/${executionId}`; }
 function eventSourceId(event) { return typeof event.source?.id === 'string' ? event.source.id : undefined; }
-export function managedWorkerInput(job, task, context) {
+export async function managedWorkerInput(job, task, context) {
     if (!['codex', 'chatgpt'].includes(task.adapter) || !job.repository || job.prNumber <= 0)
         return task.input;
+    const selectedAgent = task.agentName && context ? await agentContractPrompt(context, task.agentName) : '';
+    const selectedGraph = task.agentGraph && context ? await agentGraphPrompt(context, task.agentGraph) : '';
     if (!task.output)
         throw new Error(`Task ${task.id} requires an explicit output contract`);
     if (!task.executionId)
@@ -34,7 +37,7 @@ Project: ${task.projectName ?? context?.project.name ?? 'unspecified'}
 
 Retrieve the durable job and task from GitHub before doing the work. Use whatever GitHub access this environment provides: the URLs, a GitHub integration/tool, or GitHub CLI/API. GitHub is the source of truth for task intent and declared output.
 
-${context ? executionContextPrompt(context) + '\n\n' : ''}Follow the resolved project instructions and Agents Relay/events-bus worker contracts.
+${context ? executionContextPrompt(context) + '\n\n' : ''}${selectedAgent ? selectedAgent + '\n\n' : ''}${selectedGraph ? selectedGraph + '\n\n' : ''}Follow the resolved project instructions and Agents Relay/events-bus worker contracts.
 
 [Output contract]
 ${output}
@@ -243,7 +246,7 @@ export class Reconciler {
         const now = new Date().toISOString();
         const implementationTasks = job.tasks.filter(item => item.agentName !== 'reviewer' && !this.isSupersededTask(item));
         const reviewerRouting = await this.selectReviewer(implementationTasks);
-        const task = { jobId: job.id, id, kind: 'work', priority: job.priority, storySize: 'M', projectName: job.title, agentName: 'reviewer', parentTaskId: null, dependencies: implementationTasks.map(item => item.id), capabilities: ['review'], workerSelection: reviewerRouting.selection, adapter: reviewerRouting.candidate.adapter, input: `Review PR #${job.prNumber} at head SHA ${headSha}. Objective: ${job.objective ?? job.description ?? job.title}. First publish task.started using the caller-provided execution source identity, 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}. For review.changes_required, include every actionable finding in data.review.issues as an array of concise issue strings; Relay will create one durable fix task containing all findings. Do not modify code. When auto-merge is enabled, Relay will merge this exact reviewed head after review.approved.`, output: { kind: 'task_pr' }, routing: reviewerRouting.candidate.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 };
+        const task = { jobId: job.id, id, kind: 'work', priority: job.priority, storySize: 'M', projectName: job.title, agentName: 'reviewer', parentTaskId: null, dependencies: implementationTasks.map(item => item.id), capabilities: ['review'], workerSelection: reviewerRouting.selection, adapter: reviewerRouting.candidate.adapter, input: `Review existing PR #${job.prNumber} at exactly head SHA ${headSha}. Job objective: ${job.objective ?? job.description ?? job.title}. Use the selected reviewer agent contract as the authoritative review protocol.`, output: { kind: 'task_pr' }, routing: reviewerRouting.candidate.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.updatedAt = now;
@@ -505,7 +508,7 @@ export class Reconciler {
         const controller = new AbortController();
         let execution;
         const sourceId = executionEventSource(job.id, task.id, durableExecutionId);
-        const workerInput = managedWorkerInput(job, task, executionContext);
+        const workerInput = await managedWorkerInput(job, task, executionContext);
         const workerTask = { ...task, input: workerInput, routing: task.routing ? { ...task.routing, cwd: task.routing.cwd ?? executionContext.project.path } : task.routing };
         const startAckSetup = task.adapter === 'chatgpt' ? await this.startAck(job.id, task.id, sourceId, Date.now(), this.options.startAckTimeoutMs ?? chatGptStartAckTimeoutMs(task.timeoutMs)) : null;
         const closePolicy = task.chatgptTabClosePolicy ?? this.options.chatgptTabClosePolicy ?? adapter.tabClosePolicy ?? 'after-start';
@@ -676,7 +679,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, storySize: spec.storySize ?? 'M', projectName: spec.projectName, agentName: spec.agentName, parentTaskId: planner.id, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], workerRequirements: spec.workerRequirements, adapter: 'codex', input: spec.input, output: spec.output, continuation: spec.continuation ?? null, continuationDeliveredAt: null, state: (spec.dependencies?.length ?? 0) > 0 ? 'DRAFT' : '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'), createdAt: now, updatedAt: now, planningDecisionId: planner.id, planningSource: planner.planningSource ?? 'model-planner', planningRound: planner.planningRound ?? 1 };
+        return { jobId: job.id, id: spec.id, kind: 'work', priority: spec.priority ?? job.priority, storySize: spec.storySize ?? 'M', projectName: spec.projectName, agentName: spec.agentName, agentGraph: spec.agentGraph, parentTaskId: planner.id, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], workerRequirements: spec.workerRequirements, adapter: 'codex', input: spec.input, output: spec.output, continuation: spec.continuation ?? null, continuationDeliveredAt: null, state: (spec.dependencies?.length ?? 0) > 0 ? 'DRAFT' : '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'), createdAt: now, updatedAt: now, planningDecisionId: planner.id, planningSource: planner.planningSource ?? 'model-planner', planningRound: planner.planningRound ?? 1 };
     }
     clearExecution(taskId, executionId) {
         const live = this.live.get(taskId);
@@ -956,5 +959,5 @@ export class Reconciler {
     } }
 }
 function samePlannerChildDefinition(left, right) {
-    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 });
+    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, agentGraph: left.agentGraph, 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, agentGraph: right.agentGraph, 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

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { createSign } from 'node:crypto';
-import { parseAgent, parseJob, parseTask, renderAgentComment, renderJobComment, renderTaskComment, AGENT_MARKER, JOB_MARKER, TASK_MARKER } from './markers.js';
+import { parseAgent, parseJob, parseTask, renderAgentComment, renderJobBody, renderJobComment, renderTaskComment, AGENT_MARKER, JOB_MARKER, TASK_MARKER } from './markers.js';
 export async function loadManagedGitHubPullRequestGraphql(client, repository, prNumber, trustedAuthors) {
     const [owner, name] = repository.split('/', 2);
     if (!owner || !name || !Number.isInteger(prNumber) || prNumber <= 0 || !client.graphql)
@@ -17,7 +17,9 @@ export async function loadManagedGitHubPullRequestGraphql(client, repository, pr
         const author = row.author;
         return typeof author?.login === 'string' && trustedAuthors.has(author.login);
     });
-    const jobs = trusted.map(item => parseJob(String(item.body ?? ''))).filter((item) => item !== null);
+    const bodyJob = parseJob(typeof pr.body === 'string' ? pr.body : '');
+    const commentJobs = trusted.map(item => parseJob(String(item.body ?? ''))).filter((item) => item !== null);
+    const jobs = bodyJob ? [bodyJob] : commentJobs;
     const tasks = trusted.map(item => parseTask(String(item.body ?? ''))).filter((item) => item !== null);
     const state = String(pr.state ?? '').toUpperCase();
     const githubState = pr.merged === true ? 'MERGED' : state === 'CLOSED' ? 'CLOSED' : 'OPEN';
@@ -83,7 +85,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, storySize: task.storySize ?? 'M', 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, agentGraph: task.agentGraph,
         kind: task.kind ?? 'work', planningDecisionId: task.planningDecisionId, planningSource: task.planningSource, planningRound: task.planningRound, parentTaskId: task.parentTaskId, dependencies: task.dependencies, capabilities: task.capabilities, workerRequirements: task.workerRequirements, workerSelection: task.workerSelection, adapter: task.adapter,
         input: task.input, attachments: task.attachments, output: task.output, routing, chatgptTabClosePolicy: task.chatgptTabClosePolicy ?? 'after-start', continuation: task.continuation ?? null, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs
     };
@@ -424,13 +426,17 @@ export class GitHubStore {
     }
     async prNode() {
         const { owner, name } = this.repoParts();
-        const data = await this.graphql('query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){id state merged mergedAt closedAt}}}', { owner, name, number: this.prNumber });
+        const data = await this.graphql('query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){id state merged mergedAt closedAt body}}}', { owner, name, number: this.prNumber });
         const repository = data.repository;
         const pr = repository?.pullRequest;
         if (!pr)
             throw new Error(`Pull request #${this.prNumber} not found in ${this.repository}`);
         return pr;
     }
+    async pullRequestBody() {
+        const pr = await this.prNode();
+        return typeof pr.body === 'string' ? pr.body : '';
+    }
     async list() {
         const { owner, name } = this.repoParts();
         const all = [];
@@ -490,10 +496,16 @@ export class GitHubStore {
     }
     async load(jobId) {
         const comments = (await this.list()).filter(comment => this.isTrusted(comment));
-        const jobs = comments.map(x => parseJob(x.body)).filter((x) => x !== null && typeof x.id === 'string' && x.id.length > 0);
+        const bodyJob = parseJob(await this.pullRequestBody());
+        const commentJobs = comments.map(x => parseJob(x.body)).filter((x) => x !== null && typeof x.id === 'string' && x.id.length > 0);
+        const jobs = bodyJob ? [bodyJob] : commentJobs;
         const job = jobs.find(x => x.id === jobId);
-        if (!job)
+        if (!job) {
+            const conflicting = bodyJob ?? commentJobs[0];
+            if (conflicting)
+                throw new Error(`JOB_ID_MISMATCH: PR #${this.prNumber} is bound to ${conflicting.id}, not ${jobId}`);
             throw new Error(`JOB_MARKER_MISSING: Managed GitHub job ${jobId} has no durable ${JOB_MARKER} marker in PR #${this.prNumber}`);
+        }
         const soleTrustedJob = jobs.length === 1;
         job.tasks = comments.map(comment => {
             const task = parseTask(comment.body);
@@ -505,6 +517,16 @@ export class GitHubStore {
         return job;
     }
     async validateJobBinding(jobId) {
+        const body = await this.pullRequestBody();
+        const bodyHasMarker = body.includes(`<!-- ${JOB_MARKER} `);
+        const bodyJob = parseJob(body);
+        if (bodyHasMarker && !bodyJob)
+            throw new Error(`JOB_MARKER_MALFORMED: PR #${this.prNumber} body contains a ${JOB_MARKER} marker that cannot be parsed`);
+        if (bodyJob) {
+            if (bodyJob.id !== jobId)
+                throw new Error(`JOB_ID_MISMATCH: PR #${this.prNumber} is bound to ${bodyJob.id}, not ${jobId}`);
+            return;
+        }
         const comments = (await this.list()).filter(comment => this.isTrusted(comment));
         const markerComments = comments.filter(comment => comment.body.includes(JOB_MARKER));
         const parsed = markerComments.map(comment => parseJob(comment.body));
@@ -539,22 +561,21 @@ export class GitHubStore {
         await this.graphql('mutation($id:ID!){deleteIssueComment(input:{id:$id}){clientMutationId}}', { id: comment.nodeId });
     }
     async saveJob(job) {
+        const currentBody = await this.pullRequestBody();
+        const bodyJob = parseJob(currentBody);
+        if (bodyJob && bodyJob.id !== job.id)
+            throw new Error(`PR #${this.prNumber} body already has a different ${JOB_MARKER} marker`);
         const comments = (await this.list()).filter(comment => this.isTrusted(comment));
         const jobComments = comments.filter(comment => parseJob(comment.body) !== null);
         const conflicts = jobComments.filter(comment => parseJob(comment.body)?.id !== job.id);
         if (conflicts.length > 0)
             throw new Error(`PR #${this.prNumber} already has a different ${JOB_MARKER} marker`);
-        const matches = jobComments.filter(comment => parseJob(comment.body)?.id === job.id);
-        if (matches.length === 0)
-            await this.comment(renderJobComment(job));
-        else {
-            await this.updateComment(matches[0], renderJobComment(job));
-            for (const duplicate of matches.slice(1))
-                await this.deleteComment(duplicate);
-        }
-        const durable = (await this.list()).filter(comment => this.isTrusted(comment)).filter(comment => parseJob(comment.body)?.id === job.id);
-        if (durable.length !== 1)
-            throw new Error(`Failed to persist exactly one ${JOB_MARKER} marker for job ${job.id}`);
+        await this.updatePullRequestBody(renderJobBody(job));
+        const persisted = parseJob(await this.pullRequestBody());
+        if (!persisted || persisted.id !== job.id)
+            throw new Error(`Failed to persist ${JOB_MARKER} marker in PR #${this.prNumber} body for job ${job.id}`);
+        for (const legacy of jobComments.filter(comment => parseJob(comment.body)?.id === job.id))
+            await this.deleteComment(legacy);
     }
     async appendTask(task) {
         if (!task.jobId)
@@ -615,7 +636,9 @@ export async function listManagedGitHubJobs(client, repository, trustedAuthors)
                 const author = item.author;
                 return typeof author?.login === 'string' && trustedAuthors.has(author.login);
             });
-            const jobs = trusted.map(item => parseJob(String(item.body ?? ''))).filter((item) => item !== null);
+            const bodyJob = parseJob(typeof pr.body === 'string' ? pr.body : '');
+            const commentJobs = trusted.map(item => parseJob(String(item.body ?? ''))).filter((item) => item !== null);
+            const jobs = bodyJob ? [bodyJob] : commentJobs;
             const tasks = trusted.map(item => parseTask(String(item.body ?? ''))).filter((item) => item !== null);
             const state = String(pr.state ?? '').toUpperCase();
             const githubState = pr.merged === true || state === 'MERGED' ? 'MERGED' : state === 'CLOSED' ? 'CLOSED' : 'OPEN';

package/package.json

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

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

@@ -6,7 +6,7 @@ This contract is the shared protocol for every component that creates, schedules
 
 Job objectives and Task inputs are **Markdown** and are durable execution context, not short labels. Use Mermaid where a diagram materially explains a workflow, state model, architecture, dependency graph, relationship, or other visual structure. **Mermaid-first applies to that explanation/section, not to the entire Job objective or Task input.** Put the diagram before the prose that explains that visual model, but keep normal document structure: start with the goal/context when that is what the reader needs first. Do not force a Mermaid block at the top of every objective/input, and do not add decorative or redundant diagrams when Markdown is clearer.
 
-The trusted machine-readable Job/Task marker stores lifecycle and execution metadata only. Do **not** duplicate the Job objective or Task input inside the JSON marker; those long-form Markdown bodies remain the human-readable durable content rendered by the Job/Task comment (and, for a Job objective, the PR body). Readers reconstruct `objective` / `input` from that visible Markdown while remaining backward-compatible with legacy markers that embedded them.
+The trusted machine-readable Job/Task marker stores lifecycle and execution metadata only. Do **not** duplicate the Job objective or Task input inside marker JSON. The Job marker lives in the PR body immediately before the human-readable Job objective; Task markers live in their Task comments immediately before the human-readable Task input/result. Readers reconstruct `objective` / `input` from that visible Markdown while remaining backward-compatible with legacy markers that embedded long-form content or stored the Job marker in a separate comment.
 
 For long-form content, use files instead of shell-quoted arguments:
 
@@ -15,7 +15,7 @@ For long-form content, use files instead of shell-quoted arguments:
 
 When creating a new Job from an active discussion, the orchestrator must consolidate **all context needed to finish the Job without the originating thread** into the Job objective before creation. Include, as applicable: goal, relevant background, decisions already made, requirements, constraints, lifecycle/workflow semantics, non-goals, implementation boundaries, acceptance criteria, delivery/review instructions, and any important known issues. Do not create a Job whose objective is only a one-line summary when the discussion contains material implementation context.
 
-For a newly created PR (`job create --head`), standalone objective Markdown is required and becomes the default PR body. Updating the Job objective also updates the PR body. The trusted Job marker remains the machine-readable durable state, while the PR body and rendered Job comment expose the same objective to humans and agents.
+For a newly created PR (`job create --head`), standalone objective Markdown is required. The PR body is the single durable Job surface: one hidden `agents-relay:job:v1` marker followed by the objective Markdown. Updating Job metadata or objective updates that same body. New Jobs must not create a separate Job comment that repeats the objective. Readers must remain backward-compatible with legacy Job-comment markers, and a successful Job save may migrate such a legacy marker into the PR body only after validating the replacement before deleting the redundant legacy Job comment.
 
 ## Task producers