agents-relay 2.0.129 → 2.0.131

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

@@ -21,6 +21,7 @@ import { executionEventSource, withExecutionBoundary } from './reconciler-runtim
 export { executionEventSource } from './reconciler-runtime.js';
 import { CallbackWorkflowEffectHandler } from './workflow/effects.js';
 import { exhaustedTroubleshooterRecoveries, pendingTroubleshooterTasks, pendingTroubleshooterReopens, refreshTroubleshooterInput } from './troubleshooter.js';
+import { fallbackFailedTroubleshooters, escalateExhaustedTroubleshooters } from './troubleshooter-fallback.js';
 import { taskUsesCanonicalProjectRun } from './workspace.js';
 import { cleanupMergedJobWorktree } from './job-worktree-cleanup.js';
 import { jobHasActiveExecution } from './job-execution-slot.js';
@@ -145,6 +146,10 @@ export class Reconciler extends ReconcilerReviewBase {
                     await this.store.saveTask(recovery);
                     await this.emit(eventFor(job.id, recovery.id, original.id, 'troubleshooter.retry_queued', 'queued', `Retrying failed Troubleshooter ${recovery.id} (attempt ${recovery.attempt + 1}/${recovery.maxAttempts})`, 'orchestrator', { originalTaskId: original.id, attempt: recovery.attempt + 1, maxAttempts: recovery.maxAttempts }));
                 }
+                for (const id of await fallbackFailedTroubleshooters(this.store, jobId))
+                    await this.emit(eventFor(job.id, id, null, 'troubleshooter.retry_queued', 'queued', `Alternate model fallback scheduled for ${id}`, 'orchestrator'));
+                for (const id of await escalateExhaustedTroubleshooters(this.store, jobId))
+                    await this.emit(eventFor(job.id, id, null, 'task.blocked', 'blocked', `Fallback exhausted: human action required for ${id}`, 'orchestrator'));
                 const exhaustedJob = await this.store.load(jobId);
                 for (const exhausted of exhaustedTroubleshooterRecoveries(exhaustedJob)) {
                     const at = new Date().toISOString();
@@ -529,15 +534,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/dist/task-recovery.js

@@ -36,7 +36,7 @@ export async function requestTroubleshooterEscalation(store, jobId, recoveryTask
             result = { task: structuredClone(recovery), escalation: structuredClone(recovery.escalation), duplicate: true };
             return job;
         }
-        if (!['QUEUED', 'RUNNING'].includes(recovery.state))
+        if (!['QUEUED', 'RUNNING', 'FAILED'].includes(recovery.state))
             throw new Error(`Troubleshooter ${recoveryTaskId} cannot escalate from ${recovery.state}`);
         const proposal = { path: 'escalation_gate', targetTaskId: original.id, rootCause: request.context.trim(), solution: request.requiredAction.trim() };
         const decision = dispatchTaskResolutionSync(original, proposal, 'troubleshooter', {
@@ -44,7 +44,7 @@ export async function requestTroubleshooterEscalation(store, jobId, recoveryTask
         });
         if (!decision.accepted)
             throw new Error(`Task resolution graph rejected escalation for ${original.id}`);
-        if (!tryTransitionTaskEvent(recovery, 'task.blocked').accepted)
+        if (!tryTransitionTaskEvent(recovery, 'task.blocked', { recoverableExecution: true }).accepted)
             throw new Error(`Troubleshooter ${recoveryTaskId} cannot be blocked`);
         const escalation = {
             id: randomUUID(), originalTaskId: original.id, originalExecutionId: original.executionId ?? undefined,

package/dist/troubleshooter-fallback.js

@@ -0,0 +1,62 @@
+import { tryTransitionTaskEvent } from './scheduler.js';
+import { requestTroubleshooterEscalation } from './task-recovery.js';
+const MARKER = '[Relay execution fallback attempted]';
+const RUNTIME_FAILURE = /worker_process_failed|worker_start_timeout|terminal_event_timeout|model.*not supported|unsupported.model|delivery|process.exited|provider/i;
+/** One bounded Codex-config-default retry after normal recovery attempts. */
+export async function fallbackFailedTroubleshooters(store, jobId) {
+    const job = await store.load(jobId);
+    const queued = [];
+    for (const recovery of job.tasks.filter(task => task.agentName === 'troubleshooter' && task.state === 'FAILED' && task.attempt >= task.maxAttempts && !task.input.includes(MARKER))) {
+        const original = job.tasks.find(task => task.id === recovery.parentTaskId);
+        if (!original || original.state !== 'FAILED' || !RUNTIME_FAILURE.test(`${recovery.failureReason ?? ''} ${recovery.error ?? ''}`))
+            continue;
+        const update = (task) => {
+            if (task.state !== 'FAILED' || task.input.includes(MARKER))
+                return false;
+            if (!tryTransitionTaskEvent(task, 'retry').accepted)
+                throw new Error(`Fallback retry rejected for ${task.id}`);
+            task.maxAttempts = Math.max(task.maxAttempts, task.attempt + 1);
+            task.input += `\n\n${MARKER} Retry diagnosis with Codex config default model; report valid resolution or explicit blocker.`;
+            task.routing = { provider: '', model: '', decidedBy: 'troubleshooter-fallback:codex-config-default', decidedAt: new Date().toISOString() };
+            task.workerSelection = undefined;
+            task.leaseOwner = null;
+            task.leaseExpiresAt = null;
+            task.executionId = null;
+            return true;
+        };
+        if (store.mutateJob) {
+            await store.mutateJob(jobId, current => {
+                const task = current.tasks.find(item => item.id === recovery.id);
+                if (task && update(task))
+                    queued.push(task.id);
+                return current;
+            });
+        }
+        else {
+            const task = (await store.load(jobId)).tasks.find(item => item.id === recovery.id);
+            if (task && update(task)) {
+                await store.saveTask(task);
+                queued.push(task.id);
+            }
+        }
+    }
+    return queued;
+}
+/** The Core, not the crashed Agent, creates a durable human action gate. */
+export async function escalateExhaustedTroubleshooters(store, jobId) {
+    const job = await store.load(jobId);
+    const escalated = [];
+    for (const recovery of job.tasks.filter(task => task.agentName === 'troubleshooter' && task.state === 'FAILED' && task.attempt >= task.maxAttempts && !task.escalation)) {
+        const original = job.tasks.find(task => task.id === recovery.parentTaskId);
+        if (!original || original.state !== 'FAILED')
+            continue;
+        const context = `Automatic Troubleshooter ${recovery.id} could not produce a verified resolution after ${recovery.attempt} attempts. Last failure: ${recovery.error ?? recovery.failureReason ?? 'unknown'}. Original Task ${original.id}: ${original.error ?? original.failureReason ?? 'failed'}.`;
+        const result = await requestTroubleshooterEscalation(store, jobId, recovery.id, {
+            requiredAction: `Inspect Task ${original.id} and Troubleshooter ${recovery.id}; correct provider/runtime or supply a concrete recovery decision and supporting evidence.`,
+            resolutionCondition: `User supplies a corrective action or verified recovery instructions for Task ${original.id}.`, context,
+        });
+        if (!result.duplicate)
+            escalated.push(recovery.id);
+    }
+    return escalated;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.129",
+  "version": "2.0.131",
   "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.