agents-relay 1.0.59 → 1.0.60

package/README.md

@@ -7,13 +7,24 @@ Agents Relay is a generic TypeScript runtime for durable asynchronous agent jobs
 For GitHub-backed work, create or adopt the PR through Agents Relay itself. This guarantees the durable job marker exists before any managed task is submitted.
 
 ~~~sh
+cat > job.md <<'EOF'
+# Goal
+
+Standalone Job context. Put a Mermaid block first when a workflow/state/architecture diagram helps.
+EOF
+
 npx agents-relay job create --repo OWNER/REPO --head feat/example --base main \
-  --id job-1 --title "Objective" --body "PR description" --mode fixed
+  --id job-1 --title "Objective" --objective-file job.md --mode fixed
 
 # The orchestrator decides the initial batch separately
+cat > task.md <<'EOF'
+# Work
+
+Implement this phase using the Job objective as context.
+EOF
 npx agents-relay task create --repo OWNER/REPO --pr 12 --id job-1 \
   --task-id initial --adapter codex --provider openai --model MODEL --output task-pr \
-  --input "Implement the objective and publish a terminal event."
+  --input-file task.md
 
 npx agents-relay task create --repo OWNER/REPO --pr 12 --id job-1 \
   --task-id child --adapter codex --provider openai --model MODEL --output task-pr \
@@ -38,6 +49,8 @@ npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id chil
 
 Jobs separate durable lifecycle from derived runtime status. Durable lifecycle is `DRAFT | ACTIVE | COMPLETED | CANCELLED`: a newly created unscheduled Job is DRAFT, creating executable work activates it, and scheduled Jobs are ACTIVE because the scheduler is allowed to advance them. Runtime status (`IDLE`, `WAITING`, `QUEUED`, `RUNNING`, `BLOCKED`, `FAILED`, `REVIEWING`, `MERGE_PENDING`, `MERGED`, or `CANCELLED`) is computed from Tasks, Review, PR, and schedule facts and is never persisted as lifecycle truth.
 
+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.
+
 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
 request should start immediately and, if so, creates the first task batch

package/dist/cli.js

@@ -64,15 +64,15 @@ Example:
 
 Required: --repo OWNER/REPO, --id JOB_ID, and either --head BRANCH or --pr NUMBER.
 With --head, reuse/create the PR for that head. With --pr, bind an existing unmanaged PR.
-Common: --base BRANCH (default: main), --title TEXT, --body TEXT, --objective TEXT, --priority P0|P1|P2|P3, --mode fixed|autonomous, --no-auto-merge, --no-review.
+Common: --base BRANCH (default: main), --title TEXT, --objective-file PATH|- (preferred), --objective MARKDOWN (short/simple only), --priority P0|P1|P2|P3, --mode fixed|autonomous, --no-auto-merge, --no-review. --objective and --objective-file are mutually exclusive. For a new --head Job, one is required and must contain enough standalone context to complete the Job without the originating chat/thread. Objective Markdown is also the default PR body; --body is an explicit override.
 Job creation never creates executable tasks. The orchestrator decides the initial task batch separately. Re-running create against an already healthy Job is idempotent and does not mutate its metadata.
 
 Example:
-  npx agents-relay job create --repo OWNER/REPO --head feat/example --base main --id job-1 --title "Objective"`,
+  npx agents-relay job create --repo OWNER/REPO --head feat/example --base main --id job-1 --title "Objective" --objective-file job.md`,
     'job update': `Partially update mutable metadata on a healthy existing Job.
 
 Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID.
-Mutable: --title, --objective, --priority, --mode fixed|autonomous, --schedule, --auto-merge|--no-auto-merge, --review|--no-review, and continuation options.
+Mutable: --title, --objective-file PATH|- (preferred) or --objective MARKDOWN, --priority, --mode fixed|autonomous, --schedule, --auto-merge|--no-auto-merge, --review|--no-review, and continuation options. Updating the objective also updates the PR body.
 Unspecified fields are preserved. Marker/binding corruption is never repaired implicitly; update fails with a precise diagnostic instead.
 
 Example:
@@ -109,16 +109,16 @@ Actions:
   cancel  Cancel a Task`,
     'task create': `Create one durable Task under an existing Job.
 
-Required: normal Job storage options plus --input TEXT and --output task-pr|file. Codex/ChatGPT tasks also require --model MODEL.
+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.
 Directly-created Tasks are not wrapped in a synthetic Plan. Planner-generated Tasks are created internally by Relay from planner output.
 
 Example:
-  npx agents-relay task create --repo OWNER/REPO --pr 12 --id job-1 --task-id build --adapter codex --provider openai --model MODEL --output task-pr --input "Implement the requested change."`,
+  npx agents-relay task create --repo OWNER/REPO --pr 12 --id job-1 --task-id build --adapter codex --provider openai --model MODEL --output task-pr --input-file task.md`,
     '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, --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, --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:
@@ -233,6 +233,23 @@ class ServiceEventBus {
 }
 function arg(args, name, fallback = '') { const index = args.indexOf(name); return index >= 0 ? args[index + 1] ?? fallback : fallback; }
 function hasArg(args, name) { return args.includes(name); }
+async function readStdinText() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    return Buffer.concat(chunks).toString('utf8');
+}
+async function textOption(args, inlineFlag, fileFlag) {
+    if (hasArg(args, inlineFlag) && hasArg(args, fileFlag))
+        throw new Error(`${inlineFlag} and ${fileFlag} are mutually exclusive`);
+    if (hasArg(args, fileFlag)) {
+        const path = arg(args, fileFlag);
+        if (!path)
+            throw new Error(`${fileFlag} requires a path or - for stdin`);
+        return path === '-' ? readStdinText() : readFile(path, 'utf8');
+    }
+    return arg(args, inlineFlag);
+}
 function integerArg(args, name, fallback) { if (!hasArg(args, name))
     return fallback; const value = Number(arg(args, name)); if (!Number.isInteger(value) || value < 0)
     throw new Error(`${name} must be a non-negative integer`); return value; }
@@ -328,15 +345,15 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
         await syncScheduleLabels(client, repositoryName, job);
     return { job: await store.load(options.id), pr };
 }
-function workerTaskFromArgs(job, args, now) {
+async function workerTaskFromArgs(job, args, now) {
     const model = arg(args, '--model');
     const adapterValue = arg(args, '--adapter');
     const adapter = (adapterValue || 'codex');
     const outputKind = arg(args, '--output');
     const outputPath = arg(args, '--output-path');
-    const input = arg(args, '--input');
-    if (!input)
-        throw new Error('task create requires --input');
+    const input = await textOption(args, '--input', '--input-file');
+    if (!input.trim())
+        throw new Error('task create requires --input-file PATH|- or --input MARKDOWN');
     if (!['codex', 'chatgpt', 'orchestrator'].includes(adapter))
         throw new Error('task create --adapter must be codex, chatgpt, or orchestrator');
     if (adapter !== 'orchestrator' && !model)
@@ -397,7 +414,7 @@ async function runTaskCommand(action, args) {
         if (['COMPLETED', 'CANCELLED'].includes(job.state))
             throw new Error(`Cannot create task on terminal job ${job.id} (${job.state})`);
         const now = new Date().toISOString();
-        const task = workerTaskFromArgs(job, args, now);
+        const task = await workerTaskFromArgs(job, args, now);
         task.id = id;
         await store.appendTask(task);
         const refreshed = await store.load(job.id);
@@ -451,8 +468,8 @@ async function runTaskCommand(action, args) {
         if (!hasArg(args, '--timeout'))
             task.timeoutMs = taskOverallTimeoutMs(task.storySize, task.routing?.reasoning);
     }
-    if (hasArg(args, '--input'))
-        task.input = arg(args, '--input');
+    if (hasArg(args, '--input') || hasArg(args, '--input-file'))
+        task.input = await textOption(args, '--input', '--input-file');
     if (hasArg(args, '--project'))
         task.projectName = arg(args, '--project') || undefined;
     if (hasArg(args, '--agent'))
@@ -528,11 +545,15 @@ async function runJobCommand(action, args) {
     if (!['create', 'update', 'show', 'list', 'merge', 'cancel'].includes(action))
         throw new Error(usage);
     const repo = repository(args);
+    let createObjective;
     if (action === 'create') {
-        const taskOnlyFlags = ['--start', '--task-id', '--input', '--adapter', '--provider', '--model', '--profile', '--reasoning', '--story-size', '--project', '--agent', '--parent', '--deps', '--capabilities', '--attachments', '--max-attempts', '--timeout', '--cwd', '--chatgpt-project', '--chatgpt-tab-close-policy', '--output', '--output-path', '--draft', '--queue'];
+        const taskOnlyFlags = ['--start', '--task-id', '--input', '--input-file', '--adapter', '--provider', '--model', '--profile', '--reasoning', '--story-size', '--project', '--agent', '--parent', '--deps', '--capabilities', '--attachments', '--max-attempts', '--timeout', '--cwd', '--chatgpt-project', '--chatgpt-tab-close-policy', '--output', '--output-path', '--draft', '--queue'];
         const invalid = taskOnlyFlags.find(flag => hasArg(args, flag));
         if (invalid)
             throw new Error(`job create does not accept task execution option ${invalid}; create the job first, then let the orchestrator create the initial plan/task batch`);
+        createObjective = await textOption(args, '--objective', '--objective-file');
+        if (!arg(args, '--pr') && !createObjective.trim())
+            throw new Error('job create with --head requires --objective-file PATH|- or --objective MARKDOWN containing the complete standalone Job context');
     }
     const auth = await githubAuthContext(args);
     if (action === 'list') {
@@ -549,10 +570,11 @@ async function runJobCommand(action, args) {
     if (action === 'create') {
         if (!prNumber && !arg(args, '--head'))
             throw new Error('job create requires either --head or --pr');
+        const objective = createObjective ?? '';
         const result = await ensureManagedGitHubJob(auth.client, repo, auth.trustedAuthors, {
             id,
             title: arg(args, '--title') || undefined,
-            objective: arg(args, '--objective') || undefined,
+            objective: objective || undefined,
             priority: priority(args),
             executionMode: requestedExecutionMode(args),
             schedule: scheduleFromArgs(args),
@@ -562,7 +584,7 @@ async function runJobCommand(action, args) {
             prNumber,
             head: arg(args, '--head') || undefined,
             base: arg(args, '--base', 'main'),
-            body: arg(args, '--body') || undefined
+            body: arg(args, '--body') || objective || undefined
         });
         console.log(JSON.stringify({ repository: repo, pr: result.pr.number, job: result.job.id, executionMode: result.job.executionMode, state: result.job.state }, null, 2));
         return;
@@ -606,8 +628,13 @@ async function runJobCommand(action, args) {
     }
     if (hasArg(args, '--title'))
         job.title = arg(args, '--title');
-    if (hasArg(args, '--objective'))
-        job.objective = arg(args, '--objective');
+    if (hasArg(args, '--objective') || hasArg(args, '--objective-file')) {
+        const objective = await textOption(args, '--objective', '--objective-file');
+        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');
     if (hasArg(args, '--mode') || hasArg(args, '--execution-mode'))

package/dist/markers.js

@@ -20,8 +20,30 @@ export function parseMarker(body, label) {
     }
     return null;
 }
-export function renderJobComment(job) { return `${marker(JOB_MARKER, { ...job, tasks: undefined })}\n# Agents Relay job: ${job.title}\nState: ${job.state}\nPR: #${job.prNumber}`; }
-export function renderTaskComment(task) { return `${marker(TASK_MARKER, task)}\n## Task ${task.id}\nState: ${task.state}\n${task.result?.summary ?? task.input}`; }
+export function renderJobComment(job) {
+    const objective = job.objective?.trim() || '_No objective recorded._';
+    return `${marker(JOB_MARKER, { ...job, tasks: undefined })}
+# Agents Relay job: ${job.title}
+
+- **State:** ${job.state}
+- **PR:** #${job.prNumber}
+
+## Objective
+
+${objective}`;
+}
+export function renderTaskComment(task) {
+    const body = task.result?.summary ?? task.input;
+    return `${marker(TASK_MARKER, task)}
+## Task: ${task.id}
+
+- **State:** ${task.state}
+- **Priority:** ${task.priority ?? 'P2'}
+
+### Work
+
+${body}`;
+}
 export function parseJob(body) {
     const job = parseMarker(body, JOB_MARKER);
     if (!job)

package/dist/store.js

@@ -66,6 +66,7 @@ export class InMemoryStore {
     }
     async saveTask(task) { this.values.set(`${TASK_MARKER}:${task.jobId ?? ''}:${task.id}`, renderTaskComment(task)); }
     async closePullRequest() { }
+    async updatePullRequestBody(_body) { }
     async headSha() { const jobs = [...this.values.values()].map(parseJob).filter((x) => x !== null); return jobs[0]?.headSha ?? jobs[0]?.review?.headSha ?? null; }
     async listAgents() { return [...this.values.values()].map(parseAgent).filter((x) => x !== null); }
     async saveAgent(agent) { this.values.set(`${AGENT_MARKER}:${agent.id}`, renderAgentComment(agent)); }
@@ -477,6 +478,9 @@ export class GitHubStore {
     async closePullRequest() {
         await this.client.request('repos/' + this.repository + '/pulls/' + this.prNumber, { method: 'PATCH', body: JSON.stringify({ state: 'closed' }) });
     }
+    async updatePullRequestBody(body) {
+        await this.client.request('repos/' + this.repository + '/pulls/' + this.prNumber, { method: 'PATCH', body: JSON.stringify({ body }) });
+    }
     async headSha() {
         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){headRefOid}}}', { owner, name, number: this.prNumber });

package/package.json

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

package/skills/agents-relay/contracts/orchestrator-workflows.md

@@ -1,5 +1,9 @@
 # Agents Relay Orchestrator Workflows
 
+## Job context capture
+
+Before `job create`, the orchestrator converts the relevant discussion into a standalone Markdown objective. Prefer `--objective-file`; if a diagram materially clarifies workflow/state/architecture/dependencies, put Mermaid first. The objective must be sufficient for a fresh orchestrator/agent to complete the Job without access to the original conversation. Creating the Job is the context-compaction boundary: important decisions must be copied into durable Job context before work is delegated.
+
 This contract defines orchestrator-owned exception workflows that sit above normal Agents Relay task/job execution.
 
 ## Hotfix workflow

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

@@ -2,6 +2,19 @@
 
 This contract is the shared protocol for every component that creates, schedules, reviews, or executes Agents Relay jobs and tasks.
 
+## Job and Task authoring format
+
+Job objectives and Task inputs are **Markdown** and are durable execution context, not short labels. When the work has a workflow, state model, architecture, dependency graph, or relationship that is clearer visually, put a Mermaid block first and follow it with Markdown details. Otherwise use structured Markdown text directly.
+
+For long-form content, use files instead of shell-quoted arguments:
+
+- Job create/update: `--objective-file PATH` (or `--objective-file -` for stdin) is preferred. `--objective` is for short/simple content only. They are mutually exclusive.
+- Task create/update: `--input-file PATH` (or `--input-file -` for stdin) is preferred. `--input` is for short/simple content only. They are mutually exclusive.
+
+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.
+
 ## Task producers
 
 Any task producer — orchestrator, planner, or nested task-producing agent — must follow this contract.