agents-relay 1.0.130 → 1.0.131

package/dist/blockers.js

@@ -11,8 +11,8 @@ export async function registerBlockerDependency(options) {
     const task = dependentJob.tasks.find(item => item.id === options.dependentTaskId);
     if (!task)
         throw new Error(`Dependent task ${options.dependentTaskId} not found`);
-    if (!['FAILED', 'BLOCKED'].includes(task.state))
-        throw new Error(`Dependent task ${task.id} is not blocked/failed (${task.state})`);
+    if (!['DRAFT', 'FAILED', 'BLOCKED'].includes(task.state))
+        throw new Error(`Dependent task ${task.id} is not waiting/blocked/failed (${task.state})`);
     const now = options.now ?? new Date().toISOString();
     const relation = {
         repository: dependentJob.repository,
@@ -48,7 +48,7 @@ export async function registerBlockerDependency(options) {
 function obsoleteReason(task, relation) {
     if (!task)
         return 'dependent task no longer exists';
-    if (!['FAILED', 'BLOCKED'].includes(task.state))
+    if (!['DRAFT', 'FAILED', 'BLOCKED'].includes(task.state))
         return `dependent task advanced to ${task.state}`;
     if (task.attempt !== relation.blockedAttempt)
         return `dependent task advanced from attempt ${relation.blockedAttempt} to ${task.attempt}`;
@@ -81,8 +81,7 @@ export async function resolveBlockerDependencies(options) {
             continue;
         }
         const task = targetJob.tasks.find(item => item.id === relation.taskId);
-        const blockerRef = { repository: blocker.repository, prNumber: blocker.prNumber, jobId: blocker.id };
-        const matches = !!task && ['FAILED', 'BLOCKED'].includes(task.state) && task.attempt === relation.blockedAttempt && sameBlocker(task.blockedBy, blockerRef);
+        const matches = !!task && ['DRAFT', 'FAILED', 'BLOCKED'].includes(task.state) && task.attempt === relation.blockedAttempt;
         if (!matches) {
             relation.state = 'obsolete';
             relation.resolvedAt = now;
@@ -91,8 +90,13 @@ export async function resolveBlockerDependencies(options) {
             obsolete += 1;
             continue;
         }
-        task.maxAttempts = extendRetryBudget(task);
-        await transitionTaskEvent(task, 'retry');
+        if (task.state === 'DRAFT') {
+            await transitionTaskEvent(task, 'release');
+        }
+        else {
+            task.maxAttempts = extendRetryBudget(task);
+            await transitionTaskEvent(task, 'retry');
+        }
         task.error = null;
         task.leaseOwner = null;
         task.leaseExpiresAt = null;

package/dist/planner.js

@@ -129,6 +129,33 @@ export function parsePlannerResult(value) {
         throw new Error('Planner assessment must be a string');
     if (!Array.isArray(root.next_tasks))
         throw new Error('Planner next_tasks must be an array');
+    const unblockKeys = new Set();
+    const unblocksRaw = root.unblocks === undefined ? [] : root.unblocks;
+    if (!Array.isArray(unblocksRaw))
+        throw new Error('Planner unblocks must be an array when provided');
+    const unblocks = unblocksRaw.map((item, index) => {
+        const unblock = record(item, `unblocks[${index}]`);
+        const repository = optionalString(unblock.repository, `unblocks[${index}].repository`);
+        const jobId = optionalString(unblock.jobId, `unblocks[${index}].jobId`);
+        const taskId = optionalString(unblock.taskId, `unblocks[${index}].taskId`);
+        if (!repository || !/^[^/\s]+\/[^/\s]+$/.test(repository))
+            throw new Error(`Planner unblocks[${index}].repository must be OWNER/REPO`);
+        if (!jobId)
+            throw new Error(`Planner unblocks[${index}].jobId is required`);
+        if (!taskId)
+            throw new Error(`Planner unblocks[${index}].taskId is required`);
+        const prNumber = unblock.prNumber;
+        if (!Number.isInteger(prNumber) || Number(prNumber) <= 0)
+            throw new Error(`Planner unblocks[${index}].prNumber must be a positive integer`);
+        const resolutionMode = unblock.resolutionMode === undefined ? undefined : String(unblock.resolutionMode);
+        if (resolutionMode !== undefined && resolutionMode !== 'merge' && resolutionMode !== 'verified')
+            throw new Error(`Planner unblocks[${index}].resolutionMode must be merge or verified`);
+        const key = `${repository}#${prNumber}:${jobId}:${taskId}`;
+        if (unblockKeys.has(key))
+            throw new Error(`Planner unblocks contains duplicate dependent ${key}`);
+        unblockKeys.add(key);
+        return { repository, prNumber: Number(prNumber), jobId, taskId, resolutionMode: resolutionMode };
+    });
     const ids = new Set();
     const next_tasks = root.next_tasks.map((item, index) => {
         const task = record(item, `next_tasks[${index}]`);
@@ -169,7 +196,7 @@ export function parsePlannerResult(value) {
             continuation: task.continuation, maxAttempts, timeoutMs
         };
     });
-    return { objective_status: status, assessment: root.assessment, next_tasks };
+    return { objective_status: status, assessment: root.assessment, next_tasks, unblocks };
 }
 export function parsePlannerOutput(output) {
     const trimmed = output.trim();

package/dist/reconciler.js

@@ -491,6 +491,10 @@ export class Reconciler extends ReconcilerReviewBase {
         try {
             const result = parsePlannerResult(raw);
             const executionContext = await this.plannerContext(job, task);
+            if (result.unblocks.length > 0 && !this.store.registerBlockerDependent)
+                throw new Error('Durable store does not support Planner cross-Job unblock registration');
+            for (const unblock of result.unblocks)
+                await this.store.registerBlockerDependent?.(job.id, unblock);
             const children = result.next_tasks.map(spec => this.plannerChild(job, task, spec, executionContext));
             for (const child of children) {
                 const existing = job.tasks.find(item => item.id === child.id);
@@ -499,7 +503,7 @@ export class Reconciler extends ReconcilerReviewBase {
             }
             // Persist the completed decision before exposing executable children.
             task.plannerResult = result;
-            task.result = { summary: result.assessment, data: { objective_status: result.objective_status, next_tasks: result.next_tasks } };
+            task.result = { summary: result.assessment, data: { objective_status: result.objective_status, next_tasks: result.next_tasks, unblocks: result.unblocks } };
             task.error = null;
             task.plannerRetryFeedback = undefined;
             task.leaseOwner = null;

package/dist/store-github.js

@@ -1,6 +1,6 @@
 import { parseAgent, parseJob, parseTask, renderAgentComment, renderJobBody, renderTaskComment, JOB_MARKER } from './markers.js';
 import { isTaskForJob, sameTaskDefinition } from './store-task-definition.js';
-import { resolveBlockerDependencies } from './blockers.js';
+import { registerBlockerDependency, resolveBlockerDependencies } from './blockers.js';
 const TASK_WRITE_OVERLAY = new Map();
 export class GitHubStore {
     client;
@@ -118,6 +118,16 @@ export class GitHubStore {
         return ref && sha ? { ref, sha } : null;
     }
     async headSha() { return (await this.pullRequestHead())?.sha ?? null; }
+    async registerBlockerDependent(jobId, dependent) {
+        await registerBlockerDependency({
+            blockerStore: this,
+            blockerJobId: jobId,
+            dependentStore: new GitHubStore(this.client, dependent.repository, dependent.prNumber, this.trustedAuthors),
+            dependentJobId: dependent.jobId,
+            dependentTaskId: dependent.taskId,
+            resolutionMode: dependent.resolutionMode,
+        });
+    }
     async resolveBlockerDependents(jobId, resolution) {
         return await resolveBlockerDependencies({ blockerStore: this, blockerJobId: jobId, resolution, dependentStore: (repository, prNumber) => new GitHubStore(this.client, repository, prNumber, this.trustedAuthors) });
     }

package/package.json

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

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

@@ -67,7 +67,8 @@ Do not create separate Tasks merely for "analyze", "format", "call tool", "check
 - Do not repeat completed work or recreate an existing Task unless replacement work is explicitly needed.
 - Prefer independently verifiable Tasks with stable IDs, but do not split work solely to make Tasks smaller.
 - A Task describes what an agent must accomplish; never emit a shell command as a worker Task.
-- Use dependencies only when execution order actually matters.
+- Use dependencies only for Task IDs inside the current Job, and only when execution order actually matters. Never encode cross-Job or cross-repository dependencies in `dependencies`.
+- When the current Job is a prerequisite for another durable Job/Task, emit that dependent in top-level `unblocks`. The current blocker Job owns this authoritative reverse relation. Dependent-side `blockedBy` is optional observability metadata and is not the source of truth. Use `resolutionMode: "merge"` when blocker PR merge is sufficient; use `"verified"` when publication, deployment, runtime health, human approval, or another post-merge fact must be verified.
 - Describe each child Task precisely enough for worker-router to decide from the Task itself. Do not invent Codex/ChatGPT capability labels. workerRequirements is optional and should normally be omitted; use an explicit runtime only when the objective already requires that runtime.
 - Do not choose codex/chatgpt, provider/model, or usage probes.
 - Every child Task must declare exactly one output: `task_pr` or `file`.
@@ -77,7 +78,7 @@ Do not create separate Tasks merely for "analyze", "format", "call tool", "check
 
 ## Output
 
-Return exactly one JSON object with `objective_status`, `assessment`, and `next_tasks`.
+Return exactly one JSON object with `objective_status`, `assessment`, `next_tasks`, and optional top-level `unblocks`.
 
 For `objective_status: "in_progress"`, `assessment` must be Markdown containing:
 
@@ -86,7 +87,7 @@ For `objective_status: "in_progress"`, `assessment` must be Markdown containing:
 
 For `objective_status: "satisfied"`, `assessment` may be a concise evidence-based completion assessment without a graph.
 
-Each item in next_tasks contains id, input, output, and storySize. It may also contain priority, projectName, agentName, dependencies, capabilities, workerRequirements, maxAttempts, and timeoutMs. Adapter/routing fields are selected by Relay after planning; do not invent them.
+Each item in next_tasks contains id, input, output, and storySize. `unblocks`, when present, is an array of `{repository, prNumber, jobId, taskId, resolutionMode?}` records identifying Tasks that must remain waiting until the current Job resolves their blocker. It may also contain priority, projectName, agentName, dependencies, capabilities, workerRequirements, maxAttempts, and timeoutMs. Adapter/routing fields are selected by Relay after planning; do not invent them.
 
 ### Exact `next_tasks` serialization
 
@@ -105,6 +106,7 @@ A valid non-satisfied response:
 {
   "objective_status": "in_progress",
   "assessment": "```mermaid\nflowchart LR\n  A[Evidence] --> B[Content package]\n```\nOne daily package is the durable Task boundary.",
+  "unblocks": [{"repository":"org/app","prNumber":42,"jobId":"dependent-job","taskId":"consume-output","resolutionMode":"merge"}],
   "next_tasks": [
     {
       "id": "episode-2026-09-26",

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

@@ -101,9 +101,9 @@ A Task with `adapter: orchestrator` is synchronous self-work owned by the exact
 
 ## Cross-Job blocker dependencies
 
-Task `dependencies` remain local to one Job and must contain only Task IDs from that Job. Shared runtime/tool/platform blockers use a separate durable cross-Job relation. The blocker Job owns reverse `unblocks` records identifying dependent repository, PR, Job, Task, and blocked attempt. The dependent Task may carry a lightweight `blockedBy` reference for observability and deduplication.
+Task `dependencies` remain local to one Job and must contain only Task IDs from that Job. Shared runtime/tool/platform blockers use a separate durable cross-Job relation. The blocker Job owns reverse `unblocks` records identifying dependent repository, PR, Job, Task, and blocked attempt. The dependent Task may carry a lightweight `blockedBy` reference for observability and deduplication. Planner output follows the same ownership rule: when the current Job is the prerequisite, Planner declares dependents through top-level `unblocks`; Relay persists those declarations on the blocker Job via the blocker subsystem. Planner must never encode cross-Job dependencies as local `dependencies`. A dependent may be registered while its Task is still `DRAFT`, and blocker resolution releases that Task when the blocker resolves.
 
-Blocker resolution is generation-safe and idempotent: Relay retries a dependent only when it is still FAILED/BLOCKED on the recorded attempt and still points at that blocker. Otherwise the relation becomes obsolete. Merge-mode blockers resolve when the blocker PR is observed merged. Blockers requiring package publication, deployment, runtime health, human/external verification, or another post-merge fact use verified mode and resolve only through the explicit verified-resolution path. Existing failure evidence is preserved; retry uses the normal FAILED/BLOCKED -> QUEUED lifecycle transition.
+Blocker resolution is generation-safe and idempotent: Relay releases a dependent only when it is still DRAFT/FAILED/BLOCKED on the recorded attempt. The blocker-side `unblocks` record is authoritative; dependent-side `blockedBy` may be absent. Otherwise the relation becomes obsolete. Merge-mode blockers resolve when the blocker PR is observed merged. Blockers requiring package publication, deployment, runtime health, human/external verification, or another post-merge fact use verified mode and resolve only through the explicit verified-resolution path. Existing failure evidence is preserved; DRAFT dependents use the normal release transition and FAILED/BLOCKED dependents use the normal retry transition to QUEUED.
 
 ## Worker lifecycle