agents-relay 1.0.129 → 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/dist/usage.js

@@ -4,6 +4,67 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { createInterface } from 'node:readline';
 import { spawn } from 'node:child_process';
+export class BrowserWorkspaceUsageReader {
+    command;
+    timeoutMs;
+    now;
+    staleAfterMs;
+    constructor(command = 'browser-harness', timeoutMs = 10_000, now = () => new Date(), staleAfterMs = 15 * 60_000) {
+        this.command = command;
+        this.timeoutMs = timeoutMs;
+        this.now = now;
+        this.staleAfterMs = staleAfterMs;
+    }
+    async read() {
+        const observedAt = this.now().toISOString();
+        return await new Promise(resolve => {
+            const child = spawn(this.command, [], { stdio: ['pipe', 'pipe', 'ignore'] });
+            let output = '';
+            let settled = false;
+            const finish = (capacity) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                child.kill();
+                resolve(capacity);
+            };
+            const unavailable = (reason) => ({ name: 'Harness', poolSize: null, idle: null, leased: null, available: null, observedAt, reason });
+            const timer = setTimeout(() => finish(unavailable('Browser Workspace capacity probe timed out.')), this.timeoutMs);
+            child.stdout.setEncoding('utf8');
+            child.stdout.on('data', chunk => { output += chunk; });
+            child.once('error', () => finish(unavailable('Browser Workspace capacity probe could not be started.')));
+            child.once('close', code => {
+                if (settled)
+                    return;
+                const lines = output.trim().split('\n').reverse();
+                for (const line of lines) {
+                    try {
+                        const raw = JSON.parse(line);
+                        const name = typeof raw.name === 'string' ? raw.name : 'Harness';
+                        const rawObservedAt = typeof raw.observedAt === 'string' && !Number.isNaN(Date.parse(raw.observedAt)) ? raw.observedAt : observedAt;
+                        if (Date.parse(observedAt) - Date.parse(rawObservedAt) > this.staleAfterMs) {
+                            finish(unavailable('Browser Workspace capacity probe is stale.'));
+                            return;
+                        }
+                        const numberOrNull = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+                        const idle = numberOrNull(raw.idle);
+                        const leased = numberOrNull(raw.leased);
+                        const poolSize = numberOrNull(raw.poolSize);
+                        const available = typeof raw.available === 'boolean' ? raw.available : idle === null ? null : idle > 0;
+                        if (idle !== null || leased !== null || poolSize !== null || available !== null) {
+                            finish({ name, poolSize, idle, leased, available, observedAt: rawObservedAt, reason: null });
+                            return;
+                        }
+                    }
+                    catch { /* browser-harness may print startup diagnostics before JSON */ }
+                }
+                finish(unavailable(code === 0 ? 'Browser Workspace capacity probe returned no usable capacity.' : `Browser Workspace capacity probe exited with code ${code ?? 'unknown'}.`));
+            });
+            child.stdin.end('import json\nprint(json.dumps(workspace_capacity()))\n');
+        });
+    }
+}
 function finiteNumber(value) {
     if (typeof value === 'number' && Number.isFinite(value))
         return value;
@@ -320,18 +381,21 @@ export class UsageRegistry {
     zaiReader;
     deepSeekReader;
     openRouterReader;
-    constructor(openaiReader, zaiReader = new ZaiUsageReader(), deepSeekReader = null, openRouterReader = null) {
+    browserWorkspaceReader;
+    constructor(openaiReader, zaiReader = new ZaiUsageReader(), deepSeekReader = null, openRouterReader = null, browserWorkspaceReader = null) {
         this.openaiReader = openaiReader;
         this.zaiReader = zaiReader;
         this.deepSeekReader = deepSeekReader;
         this.openRouterReader = openRouterReader;
+        this.browserWorkspaceReader = browserWorkspaceReader;
     }
     async snapshot() {
-        const [openai, zai, deepseek, openrouter] = await Promise.all([
+        const [openai, zai, deepseek, openrouter, browserWorkspace] = await Promise.all([
             this.openaiReader.read(),
             this.zaiReader.read(),
             this.deepSeekReader?.read() ?? Promise.resolve(null),
             this.openRouterReader?.read() ?? Promise.resolve(null),
+            this.browserWorkspaceReader?.read() ?? Promise.resolve(null),
         ]);
         const credits = [];
         if (deepseek)
@@ -345,6 +409,7 @@ export class UsageRegistry {
                 { id: 'zai', label: 'Z.ai', usage: zai },
             ],
             credits,
+            ...(browserWorkspace ? { browserWorkspace } : {}),
         };
     }
 }
@@ -370,5 +435,5 @@ export class UnavailableUsageReader {
     }
 }
 export function codexAndZaiUsageRegistry(codexHome, _legacyWindowDays) {
-    return new UsageRegistry(new CodexApiUsageReader(), new ZaiUsageReader(), process.env.DEEPSEEK_API_KEY ? new DeepSeekCreditReader() : null, process.env.OPENROUTER_API_KEY ? new OpenRouterCreditReader() : null);
+    return new UsageRegistry(new CodexApiUsageReader(), new ZaiUsageReader(), process.env.DEEPSEEK_API_KEY ? new DeepSeekCreditReader() : null, process.env.OPENROUTER_API_KEY ? new OpenRouterCreditReader() : null, new BrowserWorkspaceUsageReader());
 }

package/dist/worker-routing.js

@@ -68,6 +68,7 @@ export function workerCandidates(adapters, registered, snapshot) {
                 resourceResetAt: resource.resetAt,
                 resourceResetInMinutes: resource.resetInMinutes,
                 resourceWindows: resource.windows,
+                browserWorkspaceCapacity: adapter.name === 'chatgpt' ? snapshot?.browserWorkspace : undefined,
             };
         });
     });
@@ -82,6 +83,8 @@ export function satisfiesWorker(candidate, requirements) {
         return false;
     if (requirements.runtime && candidate.runtime !== requirements.runtime)
         return false;
+    if (candidate.adapter === 'chatgpt' && candidate.browserWorkspaceCapacity?.idle === 0)
+        return false;
     return true;
 }
 export function eligibleWorkerCandidates(candidates, requirements) {
@@ -104,6 +107,7 @@ function selection(selected, selectedBy, decisionEvidence) {
         resourceResetAt: selected.resourceResetAt,
         resourceResetInMinutes: selected.resourceResetInMinutes,
         resourceWindows: selected.resourceWindows,
+        browserWorkspaceCapacity: selected.browserWorkspaceCapacity,
         decisionEvidence,
     };
 }
@@ -111,15 +115,21 @@ function selection(selected, selectedBy, decisionEvidence) {
 export function selectWorker(candidates, requirements) {
     const eligible = eligibleWorkerCandidates(candidates, requirements);
     if (eligible.length === 0)
-        throw new Error('No eligible worker satisfies the authoritative worker constraints');
+        throw new Error(noEligibleWorkerReason(candidates));
     const selected = deterministicWorker(eligible);
     return { candidate: selected, selection: selection(selected, 'worker-router:fallback') };
 }
+function noEligibleWorkerReason(candidates) {
+    if (candidates.some(candidate => candidate.adapter === 'chatgpt' && candidate.browserWorkspaceCapacity?.idle === 0)) {
+        return 'No eligible worker: ChatGPT Browser Workspace has no idle capacity.';
+    }
+    return 'No eligible worker satisfies the authoritative worker constraints';
+}
 /** Gather factual worker/task/resource context, then let decide() choose among legal workers. */
 export async function routeWorker(candidates, requirements, options = {}) {
     const eligible = eligibleWorkerCandidates(candidates, requirements);
     if (eligible.length === 0)
-        throw new Error('No eligible worker satisfies the authoritative worker constraints');
+        throw new Error(noEligibleWorkerReason(candidates));
     const preferredChatgptConcurrency = options.preferredChatgptConcurrency ?? DEFAULT_CHATGPT_PREFERRED_CONCURRENCY;
     const chatgptRunning = options.chatgptRunning ?? 0;
     const deterministic = deterministicWorker(eligible);
@@ -152,6 +162,7 @@ export async function routeWorker(candidates, requirements, options = {}) {
             resourceResetAt: item.resourceResetAt ?? null,
             resourceResetInMinutes: item.resourceResetInMinutes ?? null,
             resourceWindows: item.resourceWindows ?? null,
+            browserWorkspaceCapacity: item.browserWorkspaceCapacity ?? null,
         })),
     }));
     const choice = await chooseWithDecision(options.decisionEngine, options.decisionMode ?? 'off', { facts }, {

package/package.json

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