agents-relay 1.0.45 → 1.0.47

package/README.md

@@ -10,10 +10,10 @@ For GitHub-backed work, create or adopt the PR through Agents Relay itself. This
 npx agents-relay job create --repo OWNER/REPO --head feat/example --base main \
   --id job-1 --title "Objective" --body "PR description" --mode fixed
 
-# Create/reuse the managed job and submit its initial task atomically
-npx agents-relay job create --repo OWNER/REPO --head feat/example --base main \
-  --id job-1 --start --task-id initial --adapter codex --provider openai \
-  --model MODEL --output task-pr --input "Implement the objective and publish a terminal event."
+# The orchestrator decides the initial batch separately
+npx agents-relay submit --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."
 
 npx agents-relay submit --repo OWNER/REPO --pr 12 --id job-1 \
   --task-id child --adapter codex --provider openai --model MODEL --output task-pr \
@@ -31,14 +31,14 @@ npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id chil
   --capabilities model,chatgpt,browser-harness
 ~~~
 
-Jobs default to `fixed`, preserving the original submit-and-run behavior. Every
-executable task is now created by a completed durable planning decision. `job
-create --start` records `planner-0` (supplied by the orchestrator) and the
-initial task atomically from the caller's perspective; retrying the command is
-idempotent. Use `--mode autonomous` with `init` or `job create` to make
-reconciliation own planner progress. Autonomous creation with only an objective
-may create a model planner first, but it cannot materialize work until that
-planner succeeds. Fixed jobs never grow another planning round.
+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, submits the first task batch
+separately. That submit path records the orchestrator planning decision used as
+the provenance root for those tasks. A zero-task autonomous job remains idle;
+reconciliation does not invent its first planner. After an autonomous job has
+been explicitly started, later planning rounds may extend the work. Fixed jobs
+never grow another planning round.
 
 The durable status JSON and dashboard show the mode and planning provenance. An
 autonomous runtime uses the bundled `skills/agents-relay/agents/planner.agent.md` by default; `--planner-command` is an optional override
@@ -55,8 +55,7 @@ A repository heartbeat invokes `tick` at 10-minute resolution. See
 [Scheduled autonomous jobs](docs/scheduled-autonomous-jobs.md) for the exact
 operational contract.
 
-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.
+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. Job creation is always create-only. Task execution options belong to `submit`, and the orchestrator may submit zero, one, or multiple initial tasks according to user intent.
 
 To adopt an existing unmanaged PR, including a PR with no comments:
 

package/dist/cli.js

@@ -49,7 +49,7 @@ Usage:
   npx agents-relay job <create|adopt|repair> [options]
 
 Actions:
-  create  Find or create an open PR, then persist its job marker; use --start to submit the initial task
+  create  Find or create an open PR, then persist its job marker
   adopt   Attach a job marker to an existing PR
   repair  Repair duplicate markers for the same job
 
@@ -65,7 +65,6 @@ Common options:
   --schedule-next-run ISO  Optional first run (must match the cron expression)
   --missed-run-policy run|skip   Run each missed slot or skip to the next future slot
   --schedule-concurrency skip|queue  Skip or retain the slot while work is active
-  --start                   Create/reuse the job and submit its initial task
 
 Example:
   npx agents-relay job create --repo OWNER/REPO --head feat/example --base main --id job-1`,
@@ -73,8 +72,7 @@ Example:
 
 Required: --repo OWNER/REPO, --id JOB_ID, and --head BRANCH.
 Common: --base BRANCH (default: main), --title TEXT, --body TEXT, --mode fixed|autonomous, --no-auto-merge, --no-review.
-With --start, also require --adapter codex|chatgpt, --model MODEL, --output task-pr|file,
-and --input TEXT. The initial task ID defaults to 'initial'; use --task-id to override it.
+Job creation never creates executable tasks. The orchestrator decides the initial task batch separately with submit.
 
 Example:
   npx agents-relay job create --repo OWNER/REPO --head feat/example --base main --id job-1 --title "Objective"`,
@@ -297,7 +295,7 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
         if (!(error instanceof Error) || !error.message.includes('has no durable'))
             throw error;
         const now = new Date().toISOString();
-        job = { id: options.id, title: options.title || pr.title || 'Agents Relay job', objective: options.objective || pr.body || undefined, description: pr.body || undefined, priority: options.priority ?? 'P2', executionMode: options.executionMode ?? 'fixed', autoMerge: options.autoMerge ?? true, reviewEnabled: options.reviewEnabled ?? true, prNumber: pr.number, repository: repositoryName, state: 'OPEN', continuation: options.continuation ?? null, initialPlanning: options.initialTasks?.length ? { status: 'pending', decisionId: 'planner-0' } : undefined, createdAt: now, updatedAt: now, tasks: [] };
+        job = { id: options.id, title: options.title || pr.title || 'Agents Relay job', objective: options.objective || pr.body || undefined, description: pr.body || undefined, priority: options.priority ?? 'P2', executionMode: options.executionMode ?? 'fixed', autoMerge: options.autoMerge ?? true, reviewEnabled: options.reviewEnabled ?? true, prNumber: pr.number, repository: repositoryName, state: 'OPEN', continuation: options.continuation ?? null, createdAt: now, updatedAt: now, tasks: [] };
     }
     if (!job.description && pr.body)
         job.description = pr.body;
@@ -317,25 +315,7 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
         job.priority = 'P2';
     if (!job.title && pr.title)
         job.title = pr.title;
-    if (options.initialTasks?.length) {
-        const decisionId = job.initialPlanning?.decisionId ?? 'planner-0';
-        job.initialPlanning = { status: 'pending', decisionId };
-        job.updatedAt = new Date().toISOString();
-        await store.saveJob(job);
-        const decision = orchestratorPlanningDecision(job, options.initialTasks, decisionId, null, 0);
-        if (!(await store.load(options.id)).tasks.some(task => task.id === decision.id))
-            await store.appendTask(decision);
-        for (const original of options.initialTasks) {
-            const task = { ...original, parentTaskId: decision.id, planningDecisionId: decision.id, planningSource: 'orchestrator', planningRound: 0 };
-            if (!(await store.load(options.id)).tasks.some(item => item.id === task.id))
-                await store.appendTask(task);
-        }
-        job.initialPlanning = { status: 'complete', decisionId };
-        job.updatedAt = new Date().toISOString();
-        await store.saveJob(job);
-    }
-    else
-        await store.saveJob(job);
+    await store.saveJob(job);
     if (job.schedule)
         await syncScheduleLabels(client, repositoryName, job);
     return { job: await store.load(options.id), pr };
@@ -353,7 +333,7 @@ async function appendPlannedTask(store, job, task) {
     job.tasks.push(planned, decision);
     return planned;
 }
-function workerTaskFromArgs(job, args, now, requireInput = false) {
+function workerTaskFromArgs(job, args, now) {
     const model = arg(args, '--model');
     const adapterValue = arg(args, '--adapter');
     const adapter = (adapterValue || 'codex');
@@ -364,8 +344,6 @@ function workerTaskFromArgs(job, args, now, requireInput = false) {
         throw new Error('submit adapter must be codex, chatgpt, or orchestrator');
     if (adapter !== 'orchestrator' && !model)
         throw new Error('submit requires --model for codex/chatgpt tasks');
-    if (requireInput && !input)
-        throw new Error('job create --start requires --input');
     if (outputKind !== 'task-pr' && outputKind !== 'file')
         throw new Error('submit requires --output task-pr|file');
     if (outputKind === 'file' && !outputPath)
@@ -502,13 +480,11 @@ async function runJobCommand(action, args) {
     const id = arg(args, '--id');
     if (!id)
         throw new Error('--id is required for managed GitHub jobs');
-    const start = hasArg(args, '--start');
-    const initialTask = start ? workerTaskFromArgs({ id, title: '', executionMode: 'fixed', prNumber: 0, repository: repo, state: 'OPEN', continuation: null, createdAt: '', updatedAt: '', tasks: [] }, args, new Date().toISOString(), true) : undefined;
-    if (start && action !== 'create')
-        throw new Error('--start is only supported by job create');
-    if (start) {
-        if (!hasArg(args, '--adapter'))
-            throw new Error('job create --start requires --adapter codex|chatgpt');
+    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'];
+        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 submit the initial task batch`);
     }
     const auth = await githubAuthContext(args);
     const client = auth.client;
@@ -532,12 +508,9 @@ async function runJobCommand(action, args) {
         prNumber,
         head: arg(args, '--head') || undefined,
         base: arg(args, '--base', 'main'),
-        body: arg(args, '--body') || undefined,
-        initialTasks: initialTask ? [initialTask] : undefined
+        body: arg(args, '--body') || undefined
     });
-    if (start)
-        await publishWake(eventBus(args), result.job, initialTask?.id ?? 'initial', `Initial planning decision and task ${initialTask?.id ?? 'initial'} recorded`);
-    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));
+    console.log(JSON.stringify({ repository: repo, pr: result.pr.number, job: result.job.id, executionMode: result.job.executionMode, state: result.job.state }, 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 { requirements: { capabilities: ['model'] } }; }

package/dist/reconciler.js

@@ -386,6 +386,8 @@ export class Reconciler {
         if (job.initialPlanning?.status === 'pending')
             return job;
         const allPlanners = job.tasks.filter(task => task.kind === 'planner').sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+        if (allPlanners.length === 0)
+            return job;
         const slot = job.schedule?.currentRunSlot ? Date.parse(job.schedule.currentRunSlot) : Number.NaN;
         const scopedTasks = Number.isFinite(slot) ? job.tasks.filter(task => Date.parse(task.createdAt) >= slot) : job.tasks;
         const planners = scopedTasks.filter(task => task.kind === 'planner').sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));

package/package.json

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

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

@@ -40,8 +40,33 @@ A normal task never merges a PR. After all non-superseded work gates pass, Relay
 
 Final-review routing follows the same worker-selection boundary as executable work. Capability, availability, explicit reviewer constraints, and resource health are hard gates. Among eligible workers, Relay prefers a reviewer with a different worker identity from the implementation tasks; when that is unavailable it prefers a different provider/model, then falls back to the first eligible worker. The selected worker, `selectedBy` reason, and `reviewerRouting` event data are durable evidence. No provider is a universal reviewer default.
 
+## Hotfix workflow
+
+A hotfix is an orchestrator-owned fast path for a live blocking problem:
+
+1. The current active orchestrator thread patches the live/runtime target directly.
+2. It immediately reproduces the failure and verifies the fix against the live runtime.
+3. Once verified, the same logical fix is applied to canonical `main`, tested, committed, and pushed.
+4. The orchestrator completes the normal post-merge/publish reconciliation and cleanup.
+
+Do not create a blocking job/PR before fixing the live runtime. Keep the hotfix minimal and do not leave the live patch as the only durable implementation.
+
+## P0 / self job workflow
+
+A **P0 job** (alias: **self job**) is executed directly by the current active orchestrator thread:
+
+1. The orchestrator creates the durable job.
+2. The orchestrator immediately creates the required orchestrator-owned task(s); do not leave the P0 job idle.
+3. The current orchestrator thread starts executing those tasks immediately rather than delegating them to another worker.
+4. After implementation, the orchestrator performs/reconciles review against the current head.
+5. If review passes and merge requirements are satisfied, the orchestrator merges the job itself and completes normal post-merge reconciliation.
+
+`job create` still only creates durable job state; the P0 workflow requires the orchestrator to follow it immediately with task creation and execution.
+
 ## 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`.
+`job create` persists only the durable job. It never creates executable work. The top-level orchestrator owns the initial execution decision and, when the user intends the job to start, submits the first task batch separately. A zero-task autonomous job stays idle and reconciliation must not bootstrap its first planner.
+
+`fixed` jobs execute the orchestrator-provided task set and then proceed to final review. Once an autonomous job has been explicitly started by an orchestrator-provided planning batch, it may ask the planner for additional task batches. Planner-produced tasks must obey this same contract, including explicit `storySize`.
 
 A scheduled autonomous job adds cron/timezone/next-run and missed-run/concurrency policy to the trusted job marker, plus the `agents-relay:autonomous` label and one bounded time-of-day `agents-relay:next-run:*` index label. The GitHub heartbeat discovers only indexed due candidates, validates the marker's exact `nextRunAt`, claims the slot idempotently, advances the durable next run, and pulses `agents-relay:schedule-wake`. GitHub webhook delivery then wakes local Relay for planner/worker execution. While the schedule is active, each satisfied run returns the job to `WAITING` instead of entering final-review/auto-merge; older-cycle failures are historical evidence and do not block a later slot.