agents-relay 1.0.104 → 1.0.105

package/dist/reconciler-review.js

@@ -109,9 +109,22 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
         const registered = await this.store.listAgents();
         const candidates = workerCandidates(this.options.adapters, registered, usage);
         for (const task of job.tasks.filter(item => item.kind !== 'planner' && item.agentName !== 'reviewer' && item.adapter !== 'orchestrator' && ['QUEUED', 'BLOCKED'].includes(item.state) && item.output && !item.workerSelection && (item.workerRequirements || item.planningSource === 'model-planner'))) {
-            const requirements = task.workerRequirements ?? { capabilities: task.capabilities.length > 0 ? task.capabilities : ['model'] };
-            const taskFacts = { id: task.id, kind: task.kind ?? 'work', storySize: task.storySize ?? 'M', capabilities: task.capabilities };
-            const routedWorker = await routeWorker(candidates, requirements, { decisionEngine: this.options.decisionEngine, decisionMode: this.options.decisionMode, taskFacts });
+            const requirements = task.workerRequirements ?? { capabilities: [] };
+            const taskFacts = {
+                id: task.id,
+                kind: task.kind ?? 'work',
+                storySize: task.storySize ?? 'M',
+                agentName: task.agentName ?? null,
+                input: task.input,
+                attachments: task.attachments ?? [],
+                output: task.output ?? null,
+            };
+            const routedWorker = await routeWorker(candidates, requirements, {
+                decisionEngine: this.options.decisionEngine,
+                decisionMode: this.options.decisionMode,
+                taskFacts,
+                usage,
+            });
             const models = await discoverModelCandidates(routedWorker.candidate, registered, usage);
             const routingConstraints = task.routing ? { provider: task.routing.provider, model: task.routing.model, profile: task.routing.profile, reasoning: task.routing.reasoning } : undefined;
             const routedModel = await routeModel(routedWorker.candidate, models, { decisionEngine: this.options.decisionEngine, decisionMode: this.options.decisionMode, taskFacts, constraints: routingConstraints, auditStore: this.options.decisionAuditStore, auditTask: task });

package/dist/reviewer-routing.js

@@ -1,21 +1,7 @@
 function satisfies(candidate, requirements) {
-    if (candidate.availability && candidate.availability !== 'available')
+    if (candidate.availability === 'offline')
         return false;
-    if (candidate.resourceHealthy === false)
-        return false;
-    if (!requirements)
-        return true;
-    if (!requirements.capabilities.every(capability => candidate.capabilities.includes(capability)))
-        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))
+    if (requirements?.runtime && candidate.runtime !== requirements.runtime)
         return false;
     return true;
 }
@@ -29,7 +15,7 @@ function producedRoutes(tasks) {
         .filter(task => task.agentName !== 'reviewer' && task.routing)
         .map(task => `${task.routing?.provider}\0${task.routing?.model}`));
 }
-/** Select a review worker only after hard gates, then prefer execution diversity. */
+/** Select a reviewer after authoritative worker constraints, then prefer execution diversity. */
 export function selectReviewer(candidates, implementationTasks, requirements) {
     const eligible = candidates.filter(candidate => satisfies(candidate, requirements));
     if (eligible.length === 0)

package/dist/routing-policy.js

@@ -30,11 +30,7 @@ function safePolicy(value) {
 export function policyPath(explicit) {
     return explicit ?? process.env.AGENTS_RELAY_ROUTING_POLICY ?? join(process.cwd(), '.agents-relay-routing-policy.json');
 }
-export function modelRouterRulesPath(explicit) {
-    return explicit ?? process.env.AGENTS_RELAY_MODEL_ROUTER_RULES ?? join(process.cwd(), '.agents-relay-model-router-rules.md');
-}
-export async function loadModelRouterRules(explicit) {
-    const path = modelRouterRulesPath(explicit);
+async function loadRouterRules(path) {
     try {
         const text = await readFile(path, 'utf8');
         return { path, hash: createHash('sha256').update(text).digest('hex'), text };
@@ -43,12 +39,29 @@ export async function loadModelRouterRules(explicit) {
         return { path, hash: 'none', text: '' };
     }
 }
-export async function saveModelRouterRules(text, explicit) {
-    const path = modelRouterRulesPath(explicit);
+async function saveRouterRules(path, text) {
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, text, 'utf8');
     return { path, hash: createHash('sha256').update(text).digest('hex'), text };
 }
+export function modelRouterRulesPath(explicit) {
+    return explicit ?? process.env.AGENTS_RELAY_MODEL_ROUTER_RULES ?? join(process.cwd(), '.agents-relay-model-router-rules.md');
+}
+export function workerRouterRulesPath(explicit) {
+    return explicit ?? process.env.AGENTS_RELAY_WORKER_ROUTER_RULES ?? join(process.cwd(), '.agents-relay-worker-router-rules.md');
+}
+export async function loadModelRouterRules(explicit) {
+    return await loadRouterRules(modelRouterRulesPath(explicit));
+}
+export async function saveModelRouterRules(text, explicit) {
+    return await saveRouterRules(modelRouterRulesPath(explicit), text);
+}
+export async function loadWorkerRouterRules(explicit) {
+    return await loadRouterRules(workerRouterRulesPath(explicit));
+}
+export async function saveWorkerRouterRules(text, explicit) {
+    return await saveRouterRules(workerRouterRulesPath(explicit), text);
+}
 export async function loadRoutingPolicy(explicit, explicitRules) {
     const path = policyPath(explicit);
     const rules = await loadModelRouterRules(explicitRules);

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/package.json

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

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

@@ -68,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.
@@ -86,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