agents-relay 2.0.128 → 2.0.130

package/dist/cli-help.js

@@ -12,6 +12,7 @@ Commands:
   task create|update|show|list|complete|retry|unblock|cancel  Manage durable tasks
   review request           Request graph-owned review (optional thread override)
   plan                     Invoke the Planner for an existing managed Job
+  plan apply               Submit a validated Task Tree within one active Plan
   blocker add|resolve|show  Manage cross-Job blocker dependencies
   projection conflicts|resolve  Inspect and repair deterministic GitHub projection conflicts
   escalation               Run the canonical escalation graph and Neo escalation executor
@@ -168,6 +169,8 @@ Required: --task-id ID and the normal Job storage options.`,
 Required: --task-id ID, --reason TEXT, and the normal managed Job storage options. This does not change Task state and cannot supersede FAILED/BLOCKED/runnable work.`,
     plan: `Invoke the Planner against the current durable Job state.
 
+Agent submit: agents-relay plan apply --repo OWNER/REPO --pr PR_NUMBER --id JOB_ID --plan-id PLAN_ID --execution-id EXECUTION_ID --file plan.json. Validation errors reject without partial task writes and can be corrected inside the same Planner execution.
+
 Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID.
 Optional: --prompt TEXT or --prompt-file PATH|- (mutually exclusive). The prompt is additional guidance for this planning round and never replaces the durable Job objective.
 

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { configureLocalGitMerge } from './cli-local-merge-config.js';
 import { noGitHubMode } from './no-github.js';
 import { discoverLocalRelayStoreSnapshots, relayStoreDirectory } from './relay-store.js';
+import { readFile } from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
 import { once } from 'node:events';
 import { fileURLToPath } from 'node:url';
@@ -673,6 +674,32 @@ async function main() {
         console.log(helpText(command, command === 'job' || command === 'task' || command === 'context' || command === 'review' ? args[0] : undefined));
         return;
     }
+    if (command === 'plan' && args[0] === 'apply') {
+        const options = args.slice(1);
+        const jobId = arg(options, '--id');
+        const planId = arg(options, '--plan-id');
+        const executionId = arg(options, '--execution-id');
+        const path = arg(options, '--file');
+        if (!jobId || !planId || !executionId || !path)
+            throw new Error('plan apply requires --id --plan-id --execution-id --file');
+        const proposal = JSON.parse(path === '-' ? await new Promise((resolve, reject) => { let value = ''; process.stdin.setEncoding('utf8'); process.stdin.on('data', chunk => value += chunk); process.stdin.on('end', () => resolve(value)); process.stdin.on('error', reject); }) : await readFile(path, 'utf8'));
+        const storageArgs = options.filter((value, index) => value !== '--file' && options[index - 1] !== '--file');
+        const { store } = await storeFor(storageArgs);
+        await withEventBus(storageArgs, async (bus) => {
+            const reconciler = runtime(store, storageArgs, bus);
+            try {
+                console.log(JSON.stringify(await reconciler.applyPlannerTree(jobId, planId, executionId, proposal), null, 2));
+            }
+            catch (error) {
+                console.error(JSON.stringify({ ok: false, code: 'PLAN_APPLY_REJECTED', message: error instanceof Error ? error.message : String(error) }));
+                process.exitCode = 1;
+            }
+            finally {
+                await reconciler.close();
+            }
+        });
+        return;
+    }
     if (command === 'job') {
         const [action, ...jobArgs] = args;
         await runJobCommand(action ?? '', jobArgs);

package/dist/planner-runtime.js

@@ -21,9 +21,11 @@ export function activateCommittedPlannerWork(job) {
 export async function drainPlannerUnblocks(ports, jobId, planId) {
     const job = await ports.store.load(jobId);
     const plan = (job.plans ?? []).find(item => item.id === planId);
+    const pending = [...(plan?.pendingUnblocks ?? [])];
+    if (!pending.length)
+        return [];
     if (!ports.store.registerBlockerDependent)
         throw new Error("Blocker registration unavailable");
-    const pending = [...(plan?.pendingUnblocks ?? [])];
     // Persist only acknowledgments observed by this invocation. Subtract from
     // the latest transactional snapshot, never replace another drain's intents.
     const acknowledged = new Set();
@@ -61,7 +63,7 @@ export async function retryPendingPlannerUnblocks(ports, jobId) {
         await drainPlannerUnblocks(ports, jobId, plan.id);
     }
 }
-async function finishPlanner(ports, jobId, planId, executionId, error, raw) {
+export async function finishPlanner(ports, jobId, planId, executionId, error, raw, cliApply = false) {
     const live = ports.live.get(planId);
     if (live?.executionId === executionId)
         clearTimeout(live.timer);
@@ -71,6 +73,8 @@ async function finishPlanner(ports, jobId, planId, executionId, error, raw) {
     const plan = (job.plans ?? []).find(item => item.id === planId);
     if (!plan || plan.status !== "PLANNING" || plan.executionId !== executionId) {
         releaseLive();
+        if (cliApply)
+            throw new Error(`Plan ${planId} is not owned by this active execution`);
         return;
     }
     const failOrRetry = async (message) => {
@@ -115,6 +119,8 @@ async function finishPlanner(ports, jobId, planId, executionId, error, raw) {
             ports.detach(ports.reconcile(jobId), jobId, planId, 'planner retry reconciliation');
     };
     if (error) {
+        if (cliApply)
+            throw error;
         await failOrRetry(error.message);
         releaseLive();
         return;
@@ -240,6 +246,8 @@ async function finishPlanner(ports, jobId, planId, executionId, error, raw) {
             releaseLive();
             throw caught;
         }
+        if (cliApply)
+            throw caught;
         await failOrRetry(caught instanceof Error ? caught.message : String(caught));
         releaseLive();
         return;
@@ -318,7 +326,7 @@ export async function launchPlanExecution(ports, job, plan) {
     let promise;
     try {
         const executionContext = await ports.plannerContext(job, plan);
-        const context = { job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: plan.previousPlanId, trigger: plan.trigger, executionContext, retryFeedback: plan.retryFeedback, guidance: plan.guidance };
+        const context = { planExecution: { planId: plan.id, executionId }, job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: plan.previousPlanId, trigger: plan.trigger, executionContext, retryFeedback: plan.retryFeedback, guidance: plan.guidance };
         promise = planner.plan(context, controller.signal);
     }
     catch (error) {

package/dist/planner.js

@@ -415,7 +415,7 @@ export function plannerInput(context) {
     const project = context.executionContext?.project;
     return JSON.stringify({
         objective: context.objective,
-        retry_feedback: context.retryFeedback,
+        plan_execution: context.planExecution, retry_feedback: context.retryFeedback,
         caller_prompt: context.guidance,
         previous_planner_task_id: context.previousPlannerTaskId,
         plan_trigger: context.trigger,

package/dist/reconciler.js

@@ -529,15 +529,23 @@ export class Reconciler extends ReconcilerReviewBase {
                 ? this.failLaunch(job.id, task.id, durableExecutionId, error.message, 'delivery')
                 : this.runtimeSettled(job.id, task.id, durableExecutionId, null, error instanceof Error ? error.message : String(error))), job.id, task.id, 'worker runtime completion');
     }
+    async applyPlannerTree(jobId, planId, executionId, proposal) {
+        const { finishPlanner } = await import('./planner-runtime.js');
+        const { parsePlannerResult } = await import('./planner.js');
+        const ports = { store: this.store, options: this.options, live: this.plannerLive, plannerContext: (job, plan) => this.plannerContext(job, plan), emit: (event) => this.emit(event), detach: (promise, id, task, label) => this.detach(promise, id, task, label), reconcile: (id) => this.reconcile(id) };
+        await finishPlanner(ports, jobId, planId, executionId, null, parsePlannerResult(proposal), true);
+        const updated = (await this.store.load(jobId)).plans?.find(plan => plan.id === planId);
+        if (!updated || updated.status !== 'SUCCEEDED')
+            throw new Error(`Plan ${planId} was not committed`);
+        return updated;
+    }
     async launchPlanner(job, plan) {
         return launchPlanExecution({
             store: this.store,
             options: this.options,
             live: this.plannerLive,
-            plannerContext: (currentJob, currentPlan) => this.plannerContext(currentJob, currentPlan),
-            emit: event => this.emit(event),
-            detach: (promise, jobId, planId, context) => this.detach(promise, jobId, planId, context),
-            reconcile: jobId => this.reconcile(jobId),
+            plannerContext: (currentJob, currentPlan) => this.plannerContext(currentJob, currentPlan), emit: event => this.emit(event),
+            detach: (promise, jobId, planId, context) => this.detach(promise, jobId, planId, context), reconcile: jobId => this.reconcile(jobId),
         }, job, plan);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.128",
+  "version": "2.0.130",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "repository": {
     "type": "git",

package/skills/agents-relay/agents/planner.agent.md

@@ -4,7 +4,7 @@ You are the default objective planner for Agents Relay autonomous jobs.
 
 Before producing tasks, read and follow `../contracts/task-job-contract.md`.
 
-You are a pure planning agent. Relay invokes you with the durable Job, existing Tasks, previous planner rounds, and resolved project context. You return one structured planning result. You do not call the Agents Relay CLI, persist state, create Jobs, or mutate Tasks yourself.
+You are a planning agent. Relay invokes you with the durable Job, existing Tasks, previous planner rounds, and resolved project context. Your sole responsibility is to decompose the objective and create a valid Plan/Task Tree. When the invocation provides a live Plan ID and execution ID, write the proposed JSON to a temporary file and submit it with `agents-relay plan apply --repo OWNER/REPO --pr PR_NUMBER --id JOB_ID --plan-id PLAN_ID --execution-id EXECUTION_ID --file PATH`. If the CLI rejects it, correct the reported error and re-submit within the SAME Plan, up to three corrections. Do not create new Jobs, run Tasks, change statuses, or perform scheduling/recovery. On successful apply, return the same JSON as your final answer for compatibility; Relay detects the committed round and does not create duplicate Tasks. If no live execution identity is provided, return JSON and let Relay materialize it as before.
 
 Relay persists each planning round as a first-class Plan PR comment/marker before generated Task comments. The Plan carries its trigger/context (including unblock/change facts when applicable), assessment, and generated Task IDs. Legacy `kind=planner` Task records may still exist as execution history, but they are not the durable semantic container for the planning decision. Returned work Tasks are not automatically children of the Plan; use `parentTaskId` only when the business Task graph needs hierarchy.
 
@@ -19,6 +19,15 @@ For every non-satisfied objective:
 3. Mark the points in that graph that deserve durable Task boundaries.
 4. Create only the next useful executable Task batch from those boundaries.
 
+### Objective decomposition and convergence
+
+- **Never bundle independently testable acceptance layers into one giant Task.** Break objectives into separately verifiable deliverables (for example, contract tests, real-provider compliance, scheduler-driven end-to-end scenarios, and integration evidence). Give each Task concrete acceptance checks and an observable output.
+- Split a large Task when its remaining work spans distinct implementation areas, independently testable failure paths, or more than one meaningful review/recovery cycle. Put shared prerequisites in earlier Tasks and express true dependencies explicitly; independent work may run in parallel.
+- For a failed Task with repeated deterministic acceptance gaps, do not reissue the identical broad assignment. Identify the *missing acceptance cases*, create focused same-Job repair Tasks with valid `same_job_dependency` resolutions, and specify how their evidence unblocks the original Task. Preserve the original failed Task and failure history.
+- For event-driven workflows, separate basic ingress/persistence checks from real scheduler-driven multi-stage scenarios. Require negative-path, multi-failure recovery and no-false-completion evidence before claiming full objective coverage.
+- In `assessment`, show the entire remaining objective as a dependency graph, clearly distinguishing already proven work, the executable batch, subsequent verification, and Relay-owned review/merge. Never report overall `satisfied` merely because one batch has passed.
+
+
 A Task is **not** just a workflow step. Create a Task when its outcome deserves an independent durable lifecycle because it may need to be:
 
 - discussed or referenced later;