agents-relay 2.0.31 → 2.0.33

package/dist/router-rules.js

@@ -0,0 +1,101 @@
+/**
+ * Router Rules free-text parsing.
+ *
+ * The Execution Router rules file carries two explicit, user-authored sections:
+ *
+ * ```text
+ * [choices]
+ * openai: gpt-5.6-luna high, sol medium
+ * zai: glm-5.3-flash high
+ *
+ * [routing-instruction]
+ * Prefer zai until its quota resets; otherwise use the openai default.
+ * ```
+ *
+ * `[choices]` is an explicit, additive list of provider/model/reasoning routes.
+ * `[routing-instruction]` is opaque guidance forwarded to Laya verbatim: the
+ * exact section body is preserved byte-for-byte (leading and trailing
+ * whitespace, blank lines, and line endings included) so Relay never rewrites or
+ * normalizes user intent. Everything outside these sections is ignored so legacy
+ * free-text files remain valid and Relay never has to guess at intent.
+ */
+const SECTION_CHOICES = 'choices';
+const SECTION_INSTRUCTION = 'routing-instruction';
+const SECTION_HEADER = /^[ \t]*\[([a-z][a-z0-9-]*)\][ \t]*\r?$/gim;
+function sectionOf(line) {
+    const match = line.match(/^\s*\[([a-z][a-z0-9-]*)\]\s*$/i);
+    return match ? match[1].toLowerCase() : null;
+}
+function choiceKey(choice) {
+    return [choice.provider, choice.model, choice.reasoning ?? ''].join('\u0000');
+}
+/**
+ * Return the raw body of the first section named `name`, exactly as authored.
+ *
+ * The body begins after the line terminator that ends the section header line
+ * (the terminator belongs to the header) and ends at the start of the next
+ * section header line, or at end of input. Nothing inside the body is trimmed or
+ * normalized: whitespace, blank lines, and line endings are part of the
+ * forwarded instruction.
+ */
+function rawSectionBody(text, name) {
+    const headers = [];
+    for (const match of text.matchAll(SECTION_HEADER)) {
+        const lineStart = match.index ?? 0;
+        headers.push({ name: match[1].toLowerCase(), lineStart, lineEnd: lineStart + match[0].length });
+    }
+    const index = headers.findIndex(header => header.name === name);
+    if (index < 0)
+        return null;
+    let bodyStart = headers[index].lineEnd;
+    if (text[bodyStart] === '\r')
+        bodyStart += 1;
+    if (text[bodyStart] === '\n')
+        bodyStart += 1;
+    const bodyEnd = index + 1 < headers.length ? headers[index + 1].lineStart : text.length;
+    return text.slice(bodyStart, bodyEnd);
+}
+/**
+ * Parse explicit router choices and the routing instruction from Router Rules.
+ *
+ * `[choices]` entries are deduplicated deterministically (first occurrence
+ * wins). The `[routing-instruction]` body is captured verbatim.
+ */
+export function parseRouterRules(text) {
+    const choices = [];
+    const seen = new Set();
+    let section = null;
+    for (const rawLine of text.split(/\r?\n/)) {
+        const header = sectionOf(rawLine);
+        if (header !== null) {
+            section = header;
+            continue;
+        }
+        if (section === SECTION_INSTRUCTION)
+            continue;
+        if (section !== SECTION_CHOICES)
+            continue;
+        if (!rawLine.trim() || rawLine.trim().startsWith('#'))
+            continue;
+        const match = rawLine.match(/^\s*([A-Za-z0-9._-]+)\s*:\s*(.+)$/);
+        if (!match)
+            continue;
+        const provider = match[1].trim();
+        for (const segment of match[2].split(',')) {
+            const tokens = segment.trim().split(/\s+/).filter(Boolean);
+            if (tokens.length === 0)
+                continue;
+            const choice = {
+                provider,
+                model: tokens[0],
+                ...(tokens[1] ? { reasoning: tokens[1].toLowerCase() } : {}),
+            };
+            const key = choiceKey(choice);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            choices.push(choice);
+        }
+    }
+    return { choices, routingInstruction: rawSectionBody(text, SECTION_INSTRUCTION) ?? '' };
+}

package/dist/routing-policy.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { parseRouterRules } from './router-rules.js';
 const EMPTY_POLICY = {};
 function safePolicy(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -34,16 +35,16 @@ export function policyPath(explicit) {
 async function loadRouterRules(path) {
     try {
         const text = await readFile(path, 'utf8');
-        return { path, hash: createHash('sha256').update(text).digest('hex'), text };
+        return { path, hash: createHash('sha256').update(text).digest('hex'), text, parsed: parseRouterRules(text) };
     }
     catch {
-        return { path, hash: 'none', text: '' };
+        return { path, hash: 'none', text: '', parsed: parseRouterRules('') };
     }
 }
 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 };
+    return { path, hash: createHash('sha256').update(text).digest('hex'), text, parsed: parseRouterRules(text) };
 }
 export function executionRouterRulesPath(explicit) {
     return explicit ?? process.env.AGENTS_RELAY_EXECUTION_ROUTER_RULES ?? join(homedir(), '.agents-relay', 'execution-router-rules.md');

package/dist/store-github.js

@@ -1,5 +1,5 @@
 import { parseAgent, parseJob, parsePlan, parseTask, renderAgentComment, renderJobBody, renderPlanComment, renderTaskComment, JOB_MARKER } from './markers.js';
-import { isTaskForJob, sameTaskDefinition } from './store-task-definition.js';
+import { DurableDefinitionConflictError, isTaskForJob, planDefinitionDivergence, samePlanDefinition, sameTaskDefinition, taskDefinitionDivergence } from './store-task-definition.js';
 import { registerBlockerDependency, resolveBlockerDependencies } from './blockers.js';
 const TASK_WRITE_OVERLAY = new Map();
 const PLAN_WRITE_OVERLAY = new Map();
@@ -322,8 +322,8 @@ export class GitHubStore {
             return;
         }
         const existing = parsePlan(matches[0].body);
-        if (!existing || JSON.stringify({ ...existing, planUrl: undefined }) !== JSON.stringify({ ...plan, planUrl: undefined }))
-            throw new Error(`Plan ${plan.id} already exists with a different definition`);
+        if (!existing || !samePlanDefinition(existing, plan))
+            throw new DurableDefinitionConflictError('plan', 'append_plan', plan.jobId, plan.id, plan, existing ?? null, existing ? planDefinitionDivergence(existing, plan) : []);
         for (const duplicate of matches.slice(1))
             await this.deleteComment(duplicate);
     }
@@ -357,8 +357,9 @@ export class GitHubStore {
             return;
         }
         const parsed = matches.map(comment => ({ comment, task: parseTask(comment.body) }));
-        if (parsed.some(item => !sameTaskDefinition(item.task, task)))
-            throw new Error(`Task ${task.id} already exists with a different definition`);
+        const divergent = parsed.find(item => !sameTaskDefinition(item.task, task));
+        if (divergent)
+            throw new DurableDefinitionConflictError('task', 'append_task', task.jobId ?? '', task.id, task, divergent.task, taskDefinitionDivergence(divergent.task, task));
         for (const duplicate of parsed.slice(1))
             await this.deleteComment(duplicate.comment);
     }

package/dist/store-task-definition.js

@@ -1,3 +1,37 @@
+/**
+ * Deterministic conflict between two different definitions that claim the same durable id.
+ *
+ * This is not a transient projection failure: the same id is already occupied by a
+ * different immutable definition, so retrying the same append can never succeed.
+ * Callers classify it once, stop consuming retry budget, and record diagnostic evidence.
+ */
+export class DurableDefinitionConflictError extends Error {
+    kind;
+    operation;
+    jobId;
+    subjectId;
+    local;
+    remote;
+    divergingFields;
+    deterministic = true;
+    constructor(kind, operation, jobId, subjectId, local, remote, divergingFields) {
+        super(kind === 'task'
+            ? `Task ${subjectId} already exists with a different definition`
+            : `Plan ${subjectId} already exists with a different definition`);
+        this.kind = kind;
+        this.operation = operation;
+        this.jobId = jobId;
+        this.subjectId = subjectId;
+        this.local = local;
+        this.remote = remote;
+        this.divergingFields = divergingFields;
+        this.name = 'DurableDefinitionConflictError';
+    }
+}
+export function isDurableDefinitionConflict(error) {
+    return error instanceof DurableDefinitionConflictError
+        || (typeof error === 'object' && error !== null && error.name === 'DurableDefinitionConflictError');
+}
 function immutableTaskDefinition(task) {
     const routing = task.routing ? {
         provider: task.routing.provider, model: task.routing.model, profile: task.routing.profile,
@@ -12,6 +46,35 @@ function immutableTaskDefinition(task) {
 export function sameTaskDefinition(left, right) {
     return JSON.stringify(immutableTaskDefinition(left)) === JSON.stringify(immutableTaskDefinition(right));
 }
+/** Plan identity ignores the resolved comment URL, which is projection metadata rather than definition. */
+export function planDefinition(plan) {
+    const { planUrl: _planUrl, ...rest } = plan;
+    return rest;
+}
+export function samePlanDefinition(left, right) {
+    return JSON.stringify(planDefinition(left)) === JSON.stringify(planDefinition(right));
+}
+function observableDefinition(kind, definition) {
+    if (typeof definition !== 'object' || definition === null)
+        return {};
+    if (kind === 'task')
+        return immutableTaskDefinition(definition);
+    const { planUrl: _planUrl, ...rest } = definition;
+    return rest;
+}
+/** Top-level field names whose definition values diverge; enough to diagnose a conflicted id. */
+export function divergingDefinitionFields(kind, left, right) {
+    const observed = observableDefinition(kind, left);
+    const other = observableDefinition(kind, right);
+    const keys = [...new Set([...Object.keys(observed), ...Object.keys(other)])].sort();
+    return keys.filter(key => JSON.stringify(observed[key]) !== JSON.stringify(other[key]));
+}
+export function taskDefinitionDivergence(left, right) {
+    return divergingDefinitionFields('task', left, right);
+}
+export function planDefinitionDivergence(left, right) {
+    return divergingDefinitionFields('plan', left, right);
+}
 export function isTaskForJob(task, jobId, soleTrustedJob) {
     if (task.jobId === jobId)
         return true;

package/dist/store.js

@@ -1,5 +1,5 @@
 import { parseAgent, parseJob, parsePlan, parseTask, renderAgentComment, renderJobComment, renderPlanComment, renderTaskComment, AGENT_MARKER, JOB_MARKER, PLAN_MARKER, TASK_MARKER } from './markers.js';
-import { isTaskForJob, sameTaskDefinition } from './store-task-definition.js';
+import { DurableDefinitionConflictError, isTaskForJob, planDefinitionDivergence, samePlanDefinition, sameTaskDefinition, taskDefinitionDivergence } from './store-task-definition.js';
 import { parsePackagePublicationMarker } from './github-webhook.js';
 function publicationFromComments(rows, trustedAuthors) {
     const allowed = rows.filter(item => {
@@ -95,9 +95,9 @@ export class InMemoryStore {
     async saveJob(job) { this.values.set(`${JOB_MARKER}:${job.id}`, renderJobComment(job)); }
     async appendPlan(plan) { const key = `${PLAN_MARKER}:${plan.jobId}:${plan.id}`; const existing = this.values.get(key); if (existing) {
         const current = parsePlan(existing);
-        if (current && JSON.stringify(current) === JSON.stringify(plan))
+        if (current && samePlanDefinition(current, plan))
             return;
-        throw new Error(`Plan ${plan.id} already exists with a different definition`);
+        throw new DurableDefinitionConflictError('plan', 'append_plan', plan.jobId, plan.id, plan, current ?? null, current ? planDefinitionDivergence(current, plan) : []);
     } this.values.set(key, renderPlanComment(plan)); }
     async savePlan(plan) { this.values.set(`${PLAN_MARKER}:${plan.jobId}:${plan.id}`, renderPlanComment(plan)); }
     async appendTask(task) {
@@ -107,7 +107,7 @@ export class InMemoryStore {
             const current = parseTask(existing);
             if (current && sameTaskDefinition(current, task))
                 return;
-            throw new Error(`Task ${task.id} already exists with a different definition`);
+            throw new DurableDefinitionConflictError('task', 'append_task', task.jobId ?? '', task.id, task, current ?? null, current ? taskDefinitionDivergence(current, task) : []);
         }
         this.values.set(key, renderTaskComment(task));
     }

package/dist/workflow/projection-conflict-v2.js

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { GraphRuntime } from './graph-v2.js';
+import { dispatchWorkflowGraphSync } from './dispatcher.js';
+const source = readFileSync(new URL('../../workflow/projection-conflict.mmd', import.meta.url), 'utf8');
+const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
+export const projectionConflictV2 = new GraphRuntime(source, {
+    states: new Set(['classify', 'retry', 'conflict']),
+    guards: { deterministicDefinitionConflict: boolGuard('deterministicDefinitionConflict') },
+    actions: {},
+    events: { 'projection.failed': { id: 'projection.failed' } },
+});
+/**
+ * Core projection-failure disposition policy.
+ *
+ * A deterministic same-id/different-definition conflict stops consuming retry budget;
+ * any other failure keeps the normal backoff/retry path. This branch is owned by the
+ * canonical Mermaid graph, not by a procedural `if` in the projection writer.
+ */
+export function decideProjectionFailure(facts) {
+    return dispatchWorkflowGraphSync(projectionConflictV2, {
+        initialState: 'classify',
+        input: { transport: 'event', id: 'projection.failed', payload: {} },
+        durableFacts: facts,
+        maxSteps: 1,
+    });
+}

package/package.json

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

package/workflow/projection-conflict.mmd

@@ -0,0 +1,11 @@
+flowchart LR
+%% relay: initial classify
+classify["state: classify"]
+retry["state: retry"]
+conflict["state: conflict"]
+
+deterministic["guard: deterministicDefinitionConflict"]
+
+classify -->|on: projection.failed| deterministic
+deterministic -->|true| conflict
+deterministic -->|false| retry