agents-relay 1.0.100 → 1.0.101

package/dist/blockers.js

@@ -0,0 +1,113 @@
+import { extendRetryBudget, transitionTaskEvent } from './scheduler.js';
+function dependentKey(value) {
+    return `${value.repository}#${value.prNumber}:${value.jobId}:${value.taskId}:a${value.blockedAttempt}`;
+}
+function sameBlocker(left, right) {
+    return !!left && left.repository === right.repository && left.prNumber === right.prNumber && left.jobId === right.jobId;
+}
+export async function registerBlockerDependency(options) {
+    const blocker = await options.blockerStore.load(options.blockerJobId);
+    const dependentJob = await options.dependentStore.load(options.dependentJobId);
+    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})`);
+    const now = options.now ?? new Date().toISOString();
+    const relation = {
+        repository: dependentJob.repository,
+        prNumber: dependentJob.prNumber,
+        jobId: dependentJob.id,
+        taskId: task.id,
+        blockedAttempt: task.attempt,
+        registeredAt: now,
+        state: 'waiting',
+    };
+    const existing = (blocker.unblocks ?? []).find(item => dependentKey(item) === dependentKey(relation));
+    const requestedMode = options.resolutionMode ?? blocker.blockerResolutionMode ?? 'merge';
+    const taskBlocker = { repository: blocker.repository, prNumber: blocker.prNumber, jobId: blocker.id, blockedAttempt: task.attempt, registeredAt: existing?.registeredAt ?? now };
+    if (existing) {
+        if (!task.blockedBy || !sameBlocker(task.blockedBy, taskBlocker) || task.blockedBy.blockedAttempt !== task.attempt) {
+            task.blockedBy = taskBlocker;
+            task.updatedAt = now;
+            await options.dependentStore.saveTask(task);
+        }
+        return existing;
+    }
+    if (blocker.blockerResolutionMode && blocker.blockerResolutionMode !== requestedMode)
+        throw new Error(`Blocker ${blocker.id} already uses ${blocker.blockerResolutionMode} resolution`);
+    blocker.blockerResolutionMode = requestedMode;
+    blocker.unblocks = [...(blocker.unblocks ?? []), relation];
+    blocker.updatedAt = now;
+    await options.blockerStore.saveJob(blocker);
+    task.blockedBy = taskBlocker;
+    task.updatedAt = now;
+    await options.dependentStore.saveTask(task);
+    return relation;
+}
+function obsoleteReason(task, relation) {
+    if (!task)
+        return 'dependent task no longer exists';
+    if (!['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}`;
+    return 'dependent task no longer matches blocker registration';
+}
+export async function resolveBlockerDependencies(options) {
+    const blocker = await options.blockerStore.load(options.blockerJobId);
+    const mode = blocker.blockerResolutionMode ?? 'merge';
+    if (mode === 'verified' && options.resolution !== 'verified') {
+        const waiting = (blocker.unblocks ?? []).filter(item => item.state === 'waiting').length;
+        return { resumed: 0, obsolete: 0, waiting };
+    }
+    const now = options.now ?? new Date().toISOString();
+    let resumed = 0;
+    let obsolete = 0;
+    for (const relation of blocker.unblocks ?? []) {
+        if (relation.state !== 'waiting')
+            continue;
+        const store = options.dependentStore(relation.repository, relation.prNumber);
+        let targetJob;
+        try {
+            targetJob = await store.load(relation.jobId);
+        }
+        catch (error) {
+            relation.state = 'obsolete';
+            relation.resolvedAt = now;
+            relation.resolution = options.resolution;
+            relation.note = error instanceof Error ? error.message : String(error);
+            obsolete += 1;
+            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);
+        if (!matches) {
+            relation.state = 'obsolete';
+            relation.resolvedAt = now;
+            relation.resolution = options.resolution;
+            relation.note = obsoleteReason(task, relation);
+            obsolete += 1;
+            continue;
+        }
+        task.maxAttempts = extendRetryBudget(task);
+        await transitionTaskEvent(task, 'retry');
+        task.error = null;
+        task.leaseOwner = null;
+        task.leaseExpiresAt = null;
+        task.executionId = null;
+        delete task.blockedBy;
+        task.updatedAt = now;
+        await store.saveTask(task);
+        relation.state = 'resumed';
+        relation.resolvedAt = now;
+        relation.resolution = options.resolution;
+        relation.note = 'dependent task requeued';
+        resumed += 1;
+    }
+    blocker.blockerResolvedAt = now;
+    blocker.updatedAt = now;
+    await options.blockerStore.saveJob(blocker);
+    return { resumed, obsolete, waiting: (blocker.unblocks ?? []).filter(item => item.state === 'waiting').length };
+}

package/dist/cli-blocker.js

@@ -0,0 +1,44 @@
+import { GitHubStore } from './store.js';
+import { githubAuthContext } from './github-auth.js';
+import { registerBlockerDependency } from './blockers.js';
+import { arg, repository } from './cli-support.js';
+import { usage } from './cli-help.js';
+export async function runBlockerCommand(action, args) {
+    if (!['add', 'resolve', 'show'].includes(action))
+        throw new Error(usage);
+    const repo = repository(args);
+    const id = arg(args, '--id');
+    const pr = Number(arg(args, '--pr'));
+    if (!id || !Number.isInteger(pr) || pr <= 0)
+        throw new Error('blocker commands require --repo, --pr, and --id for the blocker Job');
+    const auth = await githubAuthContext(args);
+    const blockerStore = new GitHubStore(auth.client, repo, pr, auth.trustedAuthors);
+    if (action === 'show') {
+        console.log(JSON.stringify(await blockerStore.load(id), null, 2));
+        return;
+    }
+    if (action === 'resolve') {
+        const summary = await blockerStore.resolveBlockerDependents(id, 'verified');
+        console.log(JSON.stringify({ blocker: id, resolution: 'verified', ...summary }, null, 2));
+        return;
+    }
+    const dependentRepo = arg(args, '--dependent-repo');
+    const dependentPr = Number(arg(args, '--dependent-pr'));
+    const dependentJob = arg(args, '--dependent-job');
+    const dependentTask = arg(args, '--dependent-task');
+    if (!dependentRepo || !Number.isInteger(dependentPr) || dependentPr <= 0 || !dependentJob || !dependentTask) {
+        throw new Error('blocker add requires --dependent-repo, --dependent-pr, --dependent-job, and --dependent-task');
+    }
+    const modeValue = arg(args, '--resolution', 'merge');
+    if (!['merge', 'verified'].includes(modeValue))
+        throw new Error('--resolution must be merge or verified');
+    const relation = await registerBlockerDependency({
+        blockerStore,
+        blockerJobId: id,
+        dependentStore: new GitHubStore(auth.client, dependentRepo, dependentPr, auth.trustedAuthors),
+        dependentJobId: dependentJob,
+        dependentTaskId: dependentTask,
+        resolutionMode: modeValue,
+    });
+    console.log(JSON.stringify(relation, null, 2));
+}

package/dist/cli-help.js

@@ -1,4 +1,4 @@
-export const usage = 'agents-relay <job|task|context|init|record|agent-register|agent-discover|reconcile|tick|serve> [options]';
+export const usage = 'agents-relay <job|task|blocker|context|init|record|agent-register|agent-discover|reconcile|tick|serve> [options]';
 const help = {
     root: `Agents Relay coordinates durable asynchronous agent jobs through GitHub pull requests.
 
@@ -8,6 +8,7 @@ Usage:
 Commands:
   job create|update|show|list|merge|cancel  Manage durable GitHub-backed jobs
   task create|update|show|list|complete|retry|cancel  Manage durable tasks
+  blocker add|resolve|show  Manage cross-Job blocker dependencies
   context resolve          Resolve shared project instructions, skills, agents, and runtimes
   init                     Create a local demo job or initialize a GitHub job
   record                   Backfill a completed task into durable history
@@ -118,6 +119,21 @@ Required: --task-id ID and the normal Job storage options.`,
     'task cancel': `Cancel one durable Task.
 
 Required: --task-id ID and the normal Job storage options.`,
+    blocker: `Manage durable cross-Job blocker dependencies.
+
+Usage:
+  npx agents-relay blocker <add|resolve|show> [options]
+
+The blocker Job owns reverse \`unblocks\` references. \`add\` registers a failed/blocked dependent task. \`resolve\` is the explicit verified-resolution path; merge-mode blockers also resolve automatically after the blocker PR is observed merged.`,
+    'blocker add': `Register a dependent failed/blocked Task on a blocker Job.
+
+Blocker: --repo OWNER/REPO --pr NUMBER --id JOB_ID.
+Dependent: --dependent-repo OWNER/REPO --dependent-pr NUMBER --dependent-job JOB_ID --dependent-task TASK_ID.
+Common: --resolution merge|verified (default merge).`,
+    'blocker resolve': `Resolve a verified blocker and safely requeue matching dependents.
+
+Required: --repo OWNER/REPO --pr NUMBER --id JOB_ID. This explicit path is required for blockers configured with --resolution verified.`,
+    'blocker show': `Show a blocker Job including its durable unblocks relations.`,
     context: `Resolve the shared execution context used by XChat and Relay.
 
 Usage:
@@ -188,5 +204,7 @@ export function helpText(command, action) {
         return action ? help[`task ${action}`] ?? help.task : help.task;
     if (command === 'context')
         return action ? help[`context ${action}`] ?? help.context : help.context;
+    if (command === 'blocker')
+        return action ? help[`blocker ${action}`] ?? help.blocker : help.blocker;
     return command ? help[command] ?? help.root : help.root;
 }

package/dist/cli.js

@@ -19,6 +19,7 @@ import { extendRetryBudget, transitionJobEvent, transitionTaskEvent } from './sc
 import { dueBuckets, processDueScheduledJobs, syncScheduleLabels } from './scheduled-jobs.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { defaultWorkspaceRoot, resolveManagedProjectPath } from './workspace.js';
+import { runBlockerCommand } from './cli-blocker.js';
 import { helpText, usage } from './cli-help.js';
 export { helpText } from './cli-help.js';
 import { SERVICE_DEFAULTS, ServiceEventBus, arg, hasArg, textOption, integerArg, repository, storeFor, saveLocal, githubStore, eventBus, publishWake, priority, storySize, executionMode, chatGptTabClosePolicy, requestedExecutionMode, continuation, scheduleFromArgs, } from './cli-support.js';
@@ -352,6 +353,7 @@ async function runJobCommand(action, args) {
         await store.mergePullRequest(headSha ?? undefined);
         await transitionJobEvent(job, 'pr.merged');
         await store.saveJob(job);
+        await store.resolveBlockerDependents(id, 'merge');
         console.log(JSON.stringify(await store.load(id), null, 2));
         return;
     }
@@ -568,6 +570,11 @@ async function main() {
         await runContextCommand(action ?? '', contextArgs);
         return;
     }
+    if (command === 'blocker') {
+        const [action, ...blockerArgs] = args;
+        await runBlockerCommand(action ?? '', blockerArgs);
+        return;
+    }
     if (command === 'init') {
         const now = new Date().toISOString();
         const job = { id: arg(args, '--id', randomUUID()), title: arg(args, '--title', 'Agents Relay job'), objective: arg(args, '--objective') || undefined, priority: priority(args), executionMode: executionMode(args), schedule: scheduleFromArgs(args), autoMerge: !hasArg(args, '--no-auto-merge'), reviewEnabled: !hasArg(args, '--no-review'), prNumber: Number(arg(args, '--pr', '0')), repository: arg(args, '--repo'), state: scheduleFromArgs(args) ? 'ACTIVE' : 'DRAFT', continuation: continuation(args), createdAt: now, updatedAt: now, tasks: [] };

package/dist/reconciler.js

@@ -127,6 +127,8 @@ export class Reconciler extends ReconcilerReviewBase {
                         await this.applyJobEffectOutcomes(job, outcomes);
                     }
                 }
+                if (prState === 'MERGED' && this.store.resolveBlockerDependents)
+                    await this.store.resolveBlockerDependents(job.id, 'merge');
                 return this.store.load(jobId);
             }
             if (job.state !== 'ACTIVE')

package/dist/store-github.js

@@ -1,5 +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';
 export class GitHubStore {
     client;
     repository;
@@ -93,6 +94,9 @@ export class GitHubStore {
         return ref && sha ? { ref, sha } : null;
     }
     async headSha() { return (await this.pullRequestHead())?.sha ?? null; }
+    async resolveBlockerDependents(jobId, resolution) {
+        return await resolveBlockerDependencies({ blockerStore: this, blockerJobId: jobId, resolution, dependentStore: (repository, prNumber) => new GitHubStore(this.client, repository, prNumber, this.trustedAuthors) });
+    }
     async load(jobId) {
         const comments = (await this.list()).filter(comment => this.isTrusted(comment));
         const bodyJob = parseJob(await this.pullRequestBody());

package/package.json

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

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

@@ -28,9 +28,9 @@ Read and follow the shared Task / Job contract and orchestrator P0/self-job work
 5. Repair:
    - For a transient failure, verify the transient condition is gone.
    - For task-local failure, make the smallest durable repair in the original Job/PR when that is within scope.
-   - For a shared platform/runtime defect, become the active orchestrator for a P0/self-job in the repository that owns the broken component. Create the durable P0 Job and its orchestrator-owned Task, fix it directly, validate, merge, and complete any required publish/deploy reconciliation.
+   - For a shared platform/runtime defect, first create or reuse the owning blocker P0/self-job. If it can be completed inside this recovery execution, fix/verify it and retry the original Task. If it cannot be completed now, register the original Task with `agents-relay blocker add` on that blocker Job and finish this Troubleshooter task; do not stay running while waiting for another Job.
    - For a genuine human/external blocker, do not fake progress. Publish task.blocked with the exact action required.
-6. Only after the blocker is removed, run `agents-relay task retry` for the original Task and reconcile its Job.
+6. For an immediate repair, only after the blocker is removed run `agents-relay task retry` for the original Task and reconcile its Job. For deferred repair, rely on the durable blocker relation: merge-mode blockers wake matching dependents after merge; release/deploy/runtime blockers use `--resolution verified` and `agents-relay blocker resolve` only after verification.
 7. Verify durable evidence that the original Task moved: at minimum QUEUED after retry, preferably a new execution / task.started / observable progress.
 8. Publish this Troubleshooter Task's terminal event only after the recovery outcome is durable.
 
@@ -43,7 +43,7 @@ Read and follow the shared Task / Job contract and orchestrator P0/self-job work
 - Repository PR creation/adoption/repair still goes through Agents Relay.
 - Keep fixes narrowly scoped; do not use a failed application task as permission for broad platform refactoring.
 - If a P0 fix publishes a package or changes a managed service, verify the released artifact and dependent service health before retrying the original Task.
-- Do not mark yourself successful merely because a repair PR was opened. Recovery succeeds when the original Task is actually retryable and has been retried.
+- Do not mark an immediate recovery successful merely because a repair PR was opened. A deferred recovery may complete after it has durably registered the exact original Task/attempt on the blocker Job; Relay then owns the later generation-safe wake-up.
 
 ## Example
 

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

@@ -98,6 +98,12 @@ A Task with `adapter: orchestrator` is synchronous self-work owned by the exact
 - Successful self-work is terminalized on the same durable Task with `task complete --task-id ... --summary ...`; do not use `record` as a substitute for a Task that was created before execution. `record` remains a backfill mechanism for work that genuinely happened outside Relay.
 - If work is intended to survive the current turn or be picked up asynchronously, use a real worker adapter rather than `orchestrator`.
 
+## 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.
+
+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.
+
 ## Worker lifecycle
 
 Relay owns process lifecycle. Workers own semantic task lifecycle. A worker must publish canonical `task.started` as its first execution action, then exactly one of `task.completed`, `task.failed`, `task.blocked`, or `task.cancelled`. Process launch/exit events do not substitute for worker semantic events.