agents-relay 1.0.103 → 1.0.105

package/dist/worker-routing.js

@@ -1,4 +1,12 @@
 import { chooseWithDecision } from './decision.js';
+import { loadWorkerRouterRules } from './routing-policy.js';
+export const DEFAULT_WORKER_ROUTER_PRINCIPLES = [
+    'Worker Router chooses only the execution worker. Model Router chooses provider/model/profile after worker selection.',
+    'Prefer ChatGPT when both workers can execute the task because it does not consume Codex coding-plan tokens and normally has access to a stronger ChatGPT Sol model.',
+    'Prefer Codex when the task requires native/local execution or computer-use abilities that are unavailable through ChatGPT plus MacBridge.',
+    'Treat coding-plan/provider quota as decision context, not worker legality. Codex may still use another provider selected later by Model Router.',
+    'When Codex/OpenAI coding quota is scarce, prefer ChatGPT unless the Codex execution environment is necessary.',
+].join('\n');
 export function usageForProvider(snapshot, provider, now = Date.now()) {
     const usage = snapshot?.providers.find(item => item.id === provider)?.usage;
     if (usage?.available) {
@@ -39,15 +47,12 @@ export function workerCandidates(adapters, registered, snapshot) {
     return adapters.filter(adapter => adapter.name !== 'orchestrator').flatMap(adapter => {
         const workers = registered.filter(worker => worker.runtime.adapter === adapter.name);
         return (workers.length > 0 ? workers : [undefined]).map(worker => {
-            const provider = worker?.runtime.provider ?? (adapter.name === 'chatgpt' ? 'chatgpt' : 'openai');
-            const resource = usageForProvider(snapshot, provider);
+            const provider = worker?.runtime.provider ?? (adapter.name === 'chatgpt' ? 'chatgpt' : undefined);
+            const resource = provider ? usageForProvider(snapshot, provider) : {};
             return {
                 workerId: worker?.id ?? adapter.id,
                 adapter: adapter.name,
-                capabilities: worker?.capabilities ?? [
-                    ...adapter.capabilities,
-                    ...(adapter.name === 'codex' ? ['local_repo', 'iterative_tools', 'long_running'] : ['web_session', 'attachments', 'interactive_ui', 'one_shot']),
-                ],
+                capabilities: worker?.capabilities ?? [...adapter.capabilities],
                 runtime: worker?.runtime.adapter ?? adapter.name,
                 trustDomains: worker?.routing.trustDomains,
                 region: worker?.routing.regions?.[0],
@@ -64,23 +69,16 @@ export function workerCandidates(adapters, registered, snapshot) {
         });
     });
 }
+/**
+ * Worker legality is intentionally narrow. Descriptive capability labels and provider
+ * quota are facts for decide(), not hard gates. An explicit runtime is retained as a
+ * compatibility/caller-owned constraint, and an explicitly offline worker is illegal.
+ */
 export function satisfiesWorker(candidate, requirements) {
-    if (candidate.availability && candidate.availability !== 'available')
-        return false;
-    if (candidate.resourceHealthy === false)
-        return false;
-    if (!requirements.capabilities.every(capability => candidate.capabilities.includes(capability)))
+    if (candidate.availability === 'offline')
         return false;
     if (requirements.runtime && candidate.runtime !== requirements.runtime)
         return false;
-    if (requirements.taskKind && candidate.taskKind !== requirements.taskKind)
-        return false;
-    if (requirements.trustDomain && !candidate.trustDomains?.includes(requirements.trustDomain))
-        return false;
-    if (requirements.region && candidate.region !== requirements.region)
-        return false;
-    if (requirements.labels && Object.entries(requirements.labels).some(([key, value]) => candidate.labels?.[key] !== value))
-        return false;
     return true;
 }
 export function eligibleWorkerCandidates(candidates, requirements) {
@@ -88,8 +86,8 @@ export function eligibleWorkerCandidates(candidates, requirements) {
 }
 function deterministicWorker(eligible) {
     return [...eligible].map((candidate, index) => ({ candidate, index })).sort((left, right) => {
-        const pressure = (item) => item.resourceUsedPercent === undefined ? 1 : item.resourceUsedPercent >= 90 ? 2 : 0;
-        return pressure(left.candidate) - pressure(right.candidate) || left.index - right.index;
+        const preference = (item) => item.adapter === 'chatgpt' ? 0 : 1;
+        return preference(left.candidate) - preference(right.candidate) || left.index - right.index;
     })[0].candidate;
 }
 function selection(selected, selectedBy, decisionEvidence) {
@@ -113,30 +111,35 @@ 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 declared requirements');
+        throw new Error('No eligible worker satisfies the authoritative worker constraints');
     const selected = deterministicWorker(eligible);
-    return { candidate: selected, selection: selection(selected, 'worker-router:requirements') };
+    return { candidate: selected, selection: selection(selected, 'worker-router:fallback') };
 }
-/** Gathered facts and hard gates stay in code; Laya only judges among legal choices. */
+/** 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 declared requirements');
+        throw new Error('No eligible worker satisfies the authoritative worker constraints');
     const deterministic = deterministicWorker(eligible);
     if (eligible.length === 1) {
         const evidence = { mode: options.decisionMode ?? 'off', fallback: true };
-        return { candidate: deterministic, selection: selection(deterministic, 'worker-router:requirements', evidence) };
+        return { candidate: deterministic, selection: selection(deterministic, 'worker-router:constraint', evidence) };
     }
+    const rules = await loadWorkerRouterRules(options.rulesPath);
     const facts = JSON.parse(JSON.stringify({
         task: options.taskFacts ?? {},
-        requirements,
+        explicit_constraints: { runtime: requirements.runtime ?? null },
+        routing_principles: DEFAULT_WORKER_ROUTER_PRINCIPLES,
+        environment_rules: rules.text,
+        usage_snapshot: options.usage ?? null,
         candidates: eligible.map(item => ({
             id: item.workerId,
             adapter: item.adapter,
-            capabilities: [...item.capabilities],
             runtime: item.runtime ?? null,
-            resourceHealthy: item.resourceHealthy ?? null,
+            availability: item.availability ?? null,
+            declaredCapabilities: [...item.capabilities],
             resourceProvider: item.resourceProvider ?? null,
+            resourceHealthy: item.resourceHealthy ?? null,
             resourceUsedPercent: item.resourceUsedPercent ?? null,
             resourceRemainingPercent: item.resourceRemainingPercent ?? null,
             resourceResetAt: item.resourceResetAt ?? null,
@@ -144,8 +147,12 @@ export async function routeWorker(candidates, requirements, options = {}) {
             resourceWindows: item.resourceWindows ?? null,
         })),
     }));
-    const choice = await chooseWithDecision(options.decisionEngine, options.decisionMode ?? 'off', { facts }, { type: 'choice', question: 'Which eligible worker is best suited to execute this task?', choices: eligible.map(item => item.workerId) }, () => deterministic.workerId);
+    const choice = await chooseWithDecision(options.decisionEngine, options.decisionMode ?? 'off', { facts }, {
+        type: 'choice',
+        question: 'Choose the best execution worker for this task. Use the task description, current usage, routing principles, and environment rules. Prefer ChatGPT when both can do the work; choose Codex when native/local execution is necessary. Do not choose a provider or model here.',
+        choices: eligible.map(item => item.workerId),
+    }, () => deterministic.workerId);
     const selected = eligible.find(item => item.workerId === choice.choice) ?? deterministic;
-    const selectedBy = choice.evidence.engine && !choice.evidence.fallback ? 'worker-router:laya' : 'worker-router:requirements';
+    const selectedBy = choice.evidence.engine && !choice.evidence.fallback ? 'worker-router:laya' : 'worker-router:fallback';
     return { candidate: selected, selection: selection(selected, selectedBy, choice.evidence) };
 }

package/dist/workflow/contracts.js

@@ -12,9 +12,6 @@ export const WORKFLOW_EVENT_NAMES = [
     'pr.closed',
     'pr.merged',
     'reconcile',
-    'reconcile.blocked',
-    'reconcile.completed',
-    'reconcile.started',
     'release',
     'retry',
     'review.approved',
@@ -23,6 +20,9 @@ export const WORKFLOW_EVENT_NAMES = [
     'task.completed',
     'task.failed',
     'task.started',
+    'watchdog.failed',
+    'worker.delivery_failed',
+    'worker.start_ack_failed',
 ];
 export const WORKFLOW_FACT_NAMES = [
     'dependenciesSatisfied',
@@ -31,6 +31,7 @@ export const WORKFLOW_FACT_NAMES = [
     'dispatchable',
     'notMerged',
     'autoMerge',
+    'recoverableExecution',
 ];
 export const WORKFLOW_MUTATION_NAMES = [
     'mutation.clearError',

package/dist/workflow/definitions.js

@@ -33,4 +33,5 @@ export const taskLifecycleWorkflow = load('task-lifecycle', {
     dependenciesUnsatisfied: booleanGuard('dependenciesUnsatisfied'),
     runnable: booleanGuard('runnable'),
     dispatchable: booleanGuard('dispatchable'),
+    recoverableExecution: booleanGuard('recoverableExecution'),
 });

package/dist/workflow/durable-transition.js

@@ -0,0 +1,45 @@
+import { tryTransitionTaskEvent } from '../scheduler.js';
+/**
+ * Runtime primitive for applying one canonical Task-graph event to fresh durable state.
+ *
+ * This class owns serialization and persistence only. It does not decide lifecycle
+ * legality: the canonical Mermaid Task graph does that through tryTransitionTaskEvent.
+ */
+export class DurableTaskTransitionRuntime {
+    store;
+    locks = new Map();
+    constructor(store) {
+        this.store = store;
+    }
+    async apply(jobId, taskId, event, options = {}) {
+        return this.withLock(`${jobId}/${taskId}`, async () => {
+            const job = await this.store.load(jobId);
+            const task = job.tasks.find(item => item.id === taskId);
+            if (!task || (options.eligible && !options.eligible(job, task)))
+                return null;
+            const from = task.state;
+            const decision = tryTransitionTaskEvent(task, event, options.facts?.(job, task) ?? {});
+            if (!decision.accepted || !decision.target)
+                return { job, task, from, decision };
+            await options.mutate?.(job, task, decision);
+            await this.store.saveTask(task);
+            return { job, task, from, decision };
+        });
+    }
+    async withLock(key, work) {
+        const previous = this.locks.get(key);
+        let release;
+        const current = new Promise(resolve => { release = resolve; });
+        this.locks.set(key, current);
+        if (previous)
+            await previous;
+        try {
+            return await work();
+        }
+        finally {
+            release();
+            if (this.locks.get(key) === current)
+                this.locks.delete(key);
+        }
+    }
+}

package/dist/workflow/runtime.js

@@ -37,3 +37,10 @@ export function applyJobWorkflowDecision(job, decision, timestamp = new Date().t
     job.state = decision.target;
     job.updatedAt = timestamp;
 }
+/** Historical repair for records that stored derived runtime status as Job lifecycle. */
+export function applyHistoricalJobCompatibilityRepair(job, target, timestamp = new Date().toISOString()) {
+    if (target !== 'COMPLETED' && target !== 'CANCELLED')
+        throw new Error(`Invalid historical Job repair target ${target}`);
+    job.state = target;
+    job.updatedAt = timestamp;
+}

package/package.json

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

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

@@ -0,0 +1,24 @@
+---
+name: implementation
+description: Implement the assigned Agents Relay task in the managed checkout and verify the durable result.
+capabilities: [implementation, local_repo, iterative_tools]
+runtime: codex
+delegation: [relay-child-task]
+restrictions: [preserve-user-changes, no-unrelated-refactors]
+---
+
+# Implementation Agent
+
+Implement the assigned Task in the current managed checkout. Treat the durable
+Job objective and Task input retrieved from GitHub as authoritative. Inspect the
+existing design before editing, keep the change narrowly scoped, and preserve
+unrelated user work.
+
+Follow the shared Agents Relay and events-bus contracts. Publish the required
+canonical `task.started` event before doing work, then exactly one terminal task
+event after the declared output is durable. Use the exact execution source
+identity supplied by Relay for every lifecycle event.
+
+Run the most relevant tests and checks for the change. Do not claim completion
+without durable implementation evidence, validation results, and a concise
+summary of changed files and remaining risks.

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

@@ -58,6 +58,8 @@ Do not create separate Tasks merely for "analyze", "format", "call tool", "check
 ## Rules
 
 - Treat durable Job/Task state as authoritative.
+- Discover visible agents from the resolved execution context before selecting an agent. Choose an existing visible agent only when it is appropriate for the Task; otherwise leave `agentName` unset. Agent discovery is runtime/context-specific, not a hardcoded global list.
+- Build `agentGraph` nodes only from agents in the discovered visible-agent catalog. Every named graph agent must be visible in the resolved planning/execution context.
 - Never invent completed work or evidence.
 - First decide whether the objective is already satisfied.
 - If satisfied, return `objective_status: "satisfied"` and `next_tasks: []`.
@@ -66,8 +68,8 @@ Do not create separate Tasks merely for "analyze", "format", "call tool", "check
 - 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.
-- Every child Task must declare `workerRequirements`; worker-router selects the worker and model-router selects provider/model/reasoning afterward.
-- Do not choose `codex`/`chatgpt`, provider/model, or usage probes.
+- 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`.
 - Every child Task must include `storySize` (`S`, `M`, or `L`); use `M` when uncertain.
 - Do not create bookkeeping, waiting, status-checking, wrapper, or planning Tasks. Your response itself is the planning round.
@@ -84,4 +86,4 @@ 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`, `workerRequirements`, `output`, and `storySize`. It may also contain priority, projectName, agentName, dependencies, capabilities, 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. 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.

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

@@ -54,13 +54,14 @@ Keep these concepts distinct: observation is not root cause; hypothesis is not r
 
 Every new model-backed executable task follows this order:
 
-1. The planner declares `workerRequirements` (capabilities and optional runtime, task-kind, trust-domain, region, and label constraints).
-2. `worker-router` is code-driven: it gathers authoritative worker/resource facts, applies capability/availability and other hard gates, then may call the generic typed `decide(request, contract)` primitive only among eligible workers.
-3. `model-router` runs after worker selection, discovers model/profile facts usable by that worker, applies model hard gates, then may use the same typed `decide()` primitive among eligible profiles. Router judgment is not a free-form agent invocation.
-4. `decide()` owns no routing facts or legality policy. Its optional Laya implementation is a transient CLI subprocess per decision; unavailable/invalid decisions fall back to deterministic routing. `src/usage.ts` remains the shared resource-fact source.
-5. Relay persists the selected worker and model routing on the durable task before launch.
+1. The planner describes the executable Task precisely. It does not invent a capability matrix for Codex versus ChatGPT. workerRequirements is optional compatibility metadata; an explicit runtime may be used only when the caller already knows the Task must use that runtime.
+2. worker-router gathers factual Task context, discovered worker availability, the current shared usage snapshot, built-in routing principles, and optional local free-text rules. Only authoritative legality facts such as an explicitly offline worker or an explicit caller-owned runtime constraint are hard gates. Descriptive capability labels, region/trust labels, and provider quota are decision facts rather than ordinary worker hard gates.
+3. When more than one legal model-backed worker exists, worker-router calls the generic typed decide(request, contract) primitive to choose the execution worker. Its default principles prefer ChatGPT when both workers can execute the Task, prefer Codex when native/local execution is necessary, and treat Codex/OpenAI quota pressure as a preference rather than proof that the Codex worker is unusable.
+4. model-router runs only after worker selection and independently chooses provider/model/profile for that worker. In particular, an exhausted OpenAI quota must not eliminate the Codex worker before Model Router has a chance to choose another Codex provider/profile.
+5. decide() owns no routing facts or legality policy. Its optional Laya implementation is a transient CLI subprocess per decision; unavailable/invalid decisions fall back deterministically. src/usage.ts remains the shared resource-fact source.
+6. Relay persists the selected worker and model routing on the durable task before launch.
 
-Planner output must not hard-code `codex`/`chatgpt`, provider preference, or usage probes. The worker-router and model-router are separate responsibilities; usage readers remain owned by `src/usage.ts` and are not duplicated in either router. Legacy task records that already contain adapter/routing metadata remain readable, but newly produced planner tasks must carry worker requirements.
+Planner output must not hard-code codex/chatgpt, provider preference, inferred worker capabilities, or usage probes. Worker Router and Model Router are separate responsibilities. Legacy task records that already contain adapter/routing/worker-requirement metadata remain readable.
 
 ## Story size
 
@@ -131,7 +132,7 @@ Job runtime status is derived, not persisted. Relay computes it from lifecycle p
 
 A normal task never merges a PR. After all non-superseded work gates pass, Relay creates a SHA-bound final review task. The reviewer emits exactly one of `review.approved`, `review.changes_required`, or `review.blocked`. When `autoMerge` is enabled (default), Relay merges only after `review.approved`, pinned to the exact reviewed head SHA. A new task or new PR head makes earlier final-review evidence stale and requires a fresh review.
 
-Final-review routing follows the same worker-selection boundary as executable work. Capability, availability, explicit reviewer constraints, and resource health are hard gates. Among eligible workers, Relay prefers a reviewer with a different worker identity from the implementation tasks; when that is unavailable it prefers a different provider/model, then falls back to the first eligible worker. The selected worker, `selectedBy` reason, and `reviewerRouting` event data are durable evidence. No provider is a universal reviewer default.
+Final-review routing follows the same factual worker-selection boundary as executable work. Explicitly offline workers and explicit reviewer runtime constraints are hard gates; provider quota and descriptive capability labels do not by themselves make a worker illegal. Among eligible workers, Relay prefers a reviewer with a different worker identity from the implementation tasks; when that is unavailable it prefers a different provider/model, then falls back to the first eligible worker. The selected worker, selectedBy reason, and reviewerRouting event data are durable evidence. No provider is a universal reviewer default.
 
 ## Job, Task, and planner ownership
 

package/workflow/task-lifecycle.mmd

@@ -14,20 +14,26 @@ stateDiagram-v2
     QUEUED --> BLOCKED: block
     QUEUED --> FAILED: fail
     QUEUED --> FAILED: effect.launchTask.failed
+    QUEUED --> FAILED: watchdog.failed
+    QUEUED --> FAILED: worker.delivery_failed
+    QUEUED --> FAILED: worker.start_ack_failed
     QUEUED --> CANCELLED: cancel
 
     RUNNING --> BLOCKED: task.blocked
     RUNNING --> SUCCEEDED: task.completed / mutation.clearError,mutation.clearFailureReason
     RUNNING --> FAILED: task.failed
+    RUNNING --> FAILED: watchdog.failed
     RUNNING --> CANCELLED: task.cancelled
 
     BLOCKED --> QUEUED: retry / mutation.clearError,mutation.clearFailureReason
     BLOCKED --> CANCELLED: cancel
 
     FAILED --> QUEUED: retry / mutation.clearError,mutation.clearFailureReason
-    FAILED --> RUNNING: reconcile.started / mutation.clearError,mutation.clearFailureReason
-    FAILED --> SUCCEEDED: reconcile.completed / mutation.clearError,mutation.clearFailureReason
-    FAILED --> BLOCKED: reconcile.blocked
+    FAILED --> RUNNING: task.started [recoverableExecution] / mutation.clearError,mutation.clearFailureReason
+    FAILED --> SUCCEEDED: task.completed [recoverableExecution] / mutation.clearError,mutation.clearFailureReason
+    FAILED --> BLOCKED: task.blocked [recoverableExecution]
+    FAILED --> FAILED: task.failed [recoverableExecution]
+    FAILED --> CANCELLED: task.cancelled [recoverableExecution]
     FAILED --> CANCELLED: cancel
 
     SUCCEEDED --> [*]