agents-relay 1.0.72 → 1.0.73

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/cli.js

@@ -635,7 +635,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/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/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';
@@ -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.73",
   "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