agents-relay 1.0.90 → 1.0.91

package/dist/scheduler.js

@@ -1,16 +1,7 @@
 import { decideJobLifecycle, decideTaskLifecycle } from './workflow/rollout.js';
-export function dependencyReady(task, tasks) { return task.dependencies.every(id => tasks.get(id)?.state === 'SUCCEEDED'); }
-export function detectCycles(tasks) { const map = new Map(tasks.map(t => [t.id, t])); const visiting = new Set(); const done = new Set(); const visit = (id) => { if (visiting.has(id))
-    throw new Error(`Dependency cycle at ${id}`); if (done.has(id))
-    return; visiting.add(id); for (const dep of map.get(id)?.dependencies ?? [])
-    visit(dep); visiting.delete(id); done.add(id); }; for (const task of tasks)
-    visit(task.id); }
-function scheduledCycleTasks(job) {
-    const slot = job.schedule?.currentRunSlot ? Date.parse(job.schedule.currentRunSlot) : Number.NaN;
-    if (!Number.isFinite(slot))
-        return job.tasks;
-    return job.tasks.filter(task => Date.parse(task.createdAt) >= slot);
-}
+import { reconcileTaskDependencies } from './workflow/task-reconcile.js';
+export { dependencyReady, detectCycles } from './workflow/task-reconcile.js';
+import { applyJobWorkflowDecision, applyTaskWorkflowDecision } from './workflow/runtime.js';
 export function completionGateSatisfied(job) {
     if (job.schedule)
         return false;
@@ -20,22 +11,10 @@ export function completionGateSatisfied(job) {
     return planners.some(task => task.state === 'SUCCEEDED' && task.plannerResult?.objective_status === 'satisfied') && job.tasks.every(task => task.state === 'SUCCEEDED');
 }
 export function schedule(job) {
-    detectCycles(job.tasks);
-    const scopedTasks = scheduledCycleTasks(job);
-    const map = new Map(job.tasks.map(t => [t.id, t]));
-    for (const task of scopedTasks) {
-        const ready = dependencyReady(task, map);
-        const facts = {
-            dependenciesSatisfied: task.dependencies.length > 0 && ready,
-            dependenciesUnsatisfied: task.dependencies.length > 0 && !ready,
-            runnable: ready,
-        };
-        const decision = decideTaskLifecycle(task, 'reconcile', facts);
-        if (decision.reason === 'ambiguous')
-            throw new Error(`Ambiguous automatic task transition from ${task.state}`);
-        if (decision.accepted && decision.target)
-            applyTaskState(task, decision.target);
-    }
+    reconcileTaskDependencies(job);
+    const scopedTasks = job.schedule?.currentRunSlot
+        ? job.tasks.filter(task => Date.parse(task.createdAt) >= Date.parse(job.schedule?.currentRunSlot ?? ''))
+        : job.tasks;
     if (job.schedule) {
         const planners = scopedTasks.filter(task => task.kind === 'planner');
         const latest = planners.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id)).at(-1);
@@ -56,15 +35,14 @@ export function extendRetryBudget(task, windowSize = 3) {
     const usedOrBudgeted = Math.max(task.maxAttempts, task.attempt);
     return Math.max(windowSize, (Math.floor(usedOrBudgeted / windowSize) + 1) * windowSize);
 }
-function applyTaskState(task, state) { task.state = state; if (['QUEUED', 'RUNNING', 'SUCCEEDED'].includes(state))
-    task.error = null; task.updatedAt = new Date().toISOString(); }
 export async function transitionTaskEvent(task, event, context = {}) {
     const decision = decideTaskLifecycle(task, event, context);
     if (!decision.accepted || !decision.target)
         throw new Error(decision.reason === 'ambiguous'
             ? `Ambiguous workflow transition from ${task.state} on ${event}`
             : `No enabled workflow transition from ${task.state} on ${event}`);
-    applyTaskState(task, decision.target);
+    applyTaskWorkflowDecision(task, decision);
+    return decision;
 }
 export async function transitionJobEvent(job, event, context = {}) {
     const decision = decideJobLifecycle(job, event, context);
@@ -72,8 +50,8 @@ export async function transitionJobEvent(job, event, context = {}) {
         throw new Error(decision.reason === 'ambiguous'
             ? `Ambiguous workflow transition from ${job.state} on ${event}`
             : `No enabled workflow transition from ${job.state} on ${event}`);
-    job.state = decision.target;
-    job.updatedAt = new Date().toISOString();
+    applyJobWorkflowDecision(job, decision);
+    return decision;
 }
 export const SCHEDULE_RESOLUTION_MS = 600_000;
 export const RUN_BUCKET_LABEL_COUNT = 144;

package/dist/store-github.js

@@ -0,0 +1,217 @@
+import { parseAgent, parseJob, parseTask, renderAgentComment, renderJobBody, renderTaskComment, JOB_MARKER } from './markers.js';
+import { isTaskForJob, sameTaskDefinition } from './store-task-definition.js';
+export class GitHubStore {
+    client;
+    repository;
+    prNumber;
+    trustedAuthors;
+    constructor(client, repository, prNumber, trustedAuthors = new Set()) {
+        this.client = client;
+        this.repository = repository;
+        this.prNumber = prNumber;
+        this.trustedAuthors = trustedAuthors;
+    }
+    isTrusted(comment) { return comment.authorLogin !== null && this.trustedAuthors.has(comment.authorLogin); }
+    repoParts() {
+        const [owner, name] = this.repository.split('/', 2);
+        if (!owner || !name)
+            throw new Error(`Invalid GitHub repository ${this.repository}`);
+        return { owner, name };
+    }
+    async graphql(query, variables) {
+        if (!this.client.graphql)
+            throw new Error('GitHub GraphQL client is required');
+        return await this.client.graphql(query, variables);
+    }
+    async prNode() {
+        const { owner, name } = this.repoParts();
+        const data = await this.graphql('query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){id state merged mergedAt closedAt body}}}', { owner, name, number: this.prNumber });
+        const repository = data.repository;
+        const pr = repository?.pullRequest;
+        if (!pr)
+            throw new Error(`Pull request #${this.prNumber} not found in ${this.repository}`);
+        return pr;
+    }
+    async pullRequestBody() {
+        const pr = await this.prNode();
+        return typeof pr.body === 'string' ? pr.body : '';
+    }
+    async list() {
+        const { owner, name } = this.repoParts();
+        const all = [];
+        let cursor = null;
+        do {
+            const data = await this.graphql('query($owner:String!,$name:String!,$number:Int!,$cursor:String){repository(owner:$owner,name:$name){pullRequest(number:$number){comments(first:100,after:$cursor){nodes{id databaseId url body updatedAt author{login}} pageInfo{hasNextPage endCursor}}}}}', { owner, name, number: this.prNumber, cursor });
+            const repository = data.repository;
+            const pr = repository?.pullRequest;
+            const comments = pr?.comments;
+            const nodes = Array.isArray(comments?.nodes) ? comments.nodes : [];
+            for (const value of nodes) {
+                const author = value.author;
+                all.push({
+                    id: Number(value.databaseId ?? 0),
+                    nodeId: typeof value.id === 'string' ? value.id : undefined,
+                    url: typeof value.url === 'string' ? value.url : undefined,
+                    body: String(value.body ?? ''),
+                    updatedAt: String(value.updatedAt ?? ''),
+                    authorLogin: typeof author?.login === 'string' ? author.login : null
+                });
+            }
+            const pageInfo = comments?.pageInfo;
+            cursor = pageInfo?.hasNextPage === true && typeof pageInfo.endCursor === 'string' ? pageInfo.endCursor : null;
+        } while (cursor);
+        return all;
+    }
+    async comments() { return this.list(); }
+    async pullRequestState() {
+        const pr = await this.prNode();
+        if (pr.merged === true || typeof pr.mergedAt === 'string')
+            return 'MERGED';
+        return String(pr.state ?? '').toUpperCase() === 'CLOSED' ? 'CLOSED' : 'OPEN';
+    }
+    async mergePullRequest(expectedHeadSha) {
+        const payload = { merge_method: 'squash' };
+        if (expectedHeadSha)
+            payload.sha = expectedHeadSha;
+        const result = await this.client.request('repos/' + this.repository + '/pulls/' + this.prNumber + '/merge', {
+            method: 'PUT',
+            body: JSON.stringify(payload),
+        });
+        if (result.merged !== true)
+            throw new Error(typeof result.message === 'string' ? result.message : 'Pull request #' + this.prNumber + ' was not merged');
+    }
+    async closePullRequest() {
+        await this.client.request('repos/' + this.repository + '/pulls/' + this.prNumber, { method: 'PATCH', body: JSON.stringify({ state: 'closed' }) });
+    }
+    async updatePullRequestBody(body) {
+        await this.client.request('repos/' + this.repository + '/pulls/' + this.prNumber, { method: 'PATCH', body: JSON.stringify({ body }) });
+    }
+    async headSha() {
+        const { owner, name } = this.repoParts();
+        const data = await this.graphql('query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){headRefOid}}}', { owner, name, number: this.prNumber });
+        const repository = data.repository;
+        const pr = repository?.pullRequest;
+        return typeof pr?.headRefOid === 'string' ? pr.headRefOid : null;
+    }
+    async load(jobId) {
+        const comments = (await this.list()).filter(comment => this.isTrusted(comment));
+        const bodyJob = parseJob(await this.pullRequestBody());
+        const commentJobs = comments.map(x => parseJob(x.body)).filter((x) => x !== null && typeof x.id === 'string' && x.id.length > 0);
+        const jobs = bodyJob ? [bodyJob] : commentJobs;
+        const job = jobs.find(x => x.id === jobId);
+        if (!job) {
+            const conflicting = bodyJob ?? commentJobs[0];
+            if (conflicting)
+                throw new Error(`JOB_ID_MISMATCH: PR #${this.prNumber} is bound to ${conflicting.id}, not ${jobId}`);
+            throw new Error(`JOB_MARKER_MISSING: Managed GitHub job ${jobId} has no durable ${JOB_MARKER} marker in PR #${this.prNumber}`);
+        }
+        const soleTrustedJob = jobs.length === 1;
+        job.tasks = comments.map(comment => {
+            const task = parseTask(comment.body);
+            if (!task)
+                return null;
+            const taskUrl = comment.url ?? (comment.id > 0 ? `https://github.com/${this.repository}/pull/${this.prNumber}#issuecomment-${comment.id}` : undefined);
+            return taskUrl ? { ...task, taskUrl } : task;
+        }).filter((x) => x !== null).filter(task => isTaskForJob(task, jobId, soleTrustedJob));
+        return job;
+    }
+    async validateJobBinding(jobId) {
+        const body = await this.pullRequestBody();
+        const bodyHasMarker = body.includes(`<!-- ${JOB_MARKER} `);
+        const bodyJob = parseJob(body);
+        if (bodyHasMarker && !bodyJob)
+            throw new Error(`JOB_MARKER_MALFORMED: PR #${this.prNumber} body contains a ${JOB_MARKER} marker that cannot be parsed`);
+        if (bodyJob) {
+            if (bodyJob.id !== jobId)
+                throw new Error(`JOB_ID_MISMATCH: PR #${this.prNumber} is bound to ${bodyJob.id}, not ${jobId}`);
+            return;
+        }
+        const comments = (await this.list()).filter(comment => this.isTrusted(comment));
+        const markerComments = comments.filter(comment => comment.body.includes(JOB_MARKER));
+        const parsed = markerComments.map(comment => parseJob(comment.body));
+        const malformed = parsed.filter(job => job === null).length;
+        if (malformed > 0)
+            throw new Error(`JOB_MARKER_MALFORMED: PR #${this.prNumber} contains ${malformed} trusted ${JOB_MARKER} marker(s) that cannot be parsed`);
+        const jobs = parsed.filter((job) => job !== null);
+        const matches = jobs.filter(job => job.id === jobId);
+        if (matches.length === 0) {
+            if (jobs.length > 0)
+                throw new Error(`JOB_ID_MISMATCH: PR #${this.prNumber} is bound to ${jobs.map(job => job.id).join(', ')}, not ${jobId}`);
+            throw new Error(`JOB_MARKER_MISSING: Managed GitHub job ${jobId} has no durable ${JOB_MARKER} marker in PR #${this.prNumber}`);
+        }
+        if (matches.length > 1)
+            throw new Error(`JOB_MARKER_DUPLICATED: PR #${this.prNumber} contains ${matches.length} trusted ${JOB_MARKER} markers for job ${jobId}`);
+        if (jobs.length > 1)
+            throw new Error(`JOB_BINDING_CONFLICT: PR #${this.prNumber} contains trusted ${JOB_MARKER} markers for multiple job ids`);
+    }
+    async listAgents() { return (await this.list()).filter(comment => this.isTrusted(comment)).map(x => parseAgent(x.body)).filter((x) => x !== null); }
+    async comment(body) {
+        const pr = await this.prNode();
+        await this.graphql('mutation($subjectId:ID!,$body:String!){addComment(input:{subjectId:$subjectId,body:$body}){commentEdge{node{id}}}}', { subjectId: pr.id, body });
+    }
+    async updateComment(comment, body) {
+        if (!comment.nodeId)
+            throw new Error('GitHub comment node id is required for GraphQL update');
+        await this.graphql('mutation($id:ID!,$body:String!){updateIssueComment(input:{id:$id,body:$body}){issueComment{id}}}', { id: comment.nodeId, body });
+    }
+    async deleteComment(comment) {
+        if (!comment.nodeId)
+            throw new Error('GitHub comment node id is required for GraphQL delete');
+        await this.graphql('mutation($id:ID!){deleteIssueComment(input:{id:$id}){clientMutationId}}', { id: comment.nodeId });
+    }
+    async saveJob(job) {
+        const currentBody = await this.pullRequestBody();
+        const bodyJob = parseJob(currentBody);
+        if (bodyJob && bodyJob.id !== job.id)
+            throw new Error(`PR #${this.prNumber} body already has a different ${JOB_MARKER} marker`);
+        const comments = (await this.list()).filter(comment => this.isTrusted(comment));
+        const jobComments = comments.filter(comment => parseJob(comment.body) !== null);
+        const conflicts = jobComments.filter(comment => parseJob(comment.body)?.id !== job.id);
+        if (conflicts.length > 0)
+            throw new Error(`PR #${this.prNumber} already has a different ${JOB_MARKER} marker`);
+        await this.updatePullRequestBody(renderJobBody(job));
+        const persisted = parseJob(await this.pullRequestBody());
+        if (!persisted || persisted.id !== job.id)
+            throw new Error(`Failed to persist ${JOB_MARKER} marker in PR #${this.prNumber} body for job ${job.id}`);
+        for (const legacy of jobComments.filter(comment => parseJob(comment.body)?.id === job.id))
+            await this.deleteComment(legacy);
+    }
+    async appendTask(task) {
+        if (!task.jobId)
+            throw new Error('GitHub task requires jobId');
+        await this.load(task.jobId);
+        const comments = (await this.list()).filter(comment => this.isTrusted(comment));
+        const matches = comments.filter(comment => {
+            const existing = parseTask(comment.body);
+            return existing !== null && existing.jobId === task.jobId && existing.id === task.id;
+        });
+        if (matches.length === 0) {
+            await this.comment(renderTaskComment(task));
+            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`);
+        for (const duplicate of parsed.slice(1))
+            await this.deleteComment(duplicate.comment);
+    }
+    async saveTask(task) {
+        const comments = (await this.list()).filter(comment => this.isTrusted(comment));
+        const existing = comments.filter(comment => { const markerTask = parseTask(comment.body); return markerTask !== null && markerTask.jobId === task.jobId && markerTask.id === task.id; });
+        if (existing.length > 0) {
+            await this.updateComment(existing[0], renderTaskComment(task));
+            for (const duplicate of existing.slice(1))
+                await this.deleteComment(duplicate);
+        }
+        else
+            await this.appendTask(task);
+    }
+    async saveAgent(agent) {
+        const comments = (await this.list()).filter(comment => this.isTrusted(comment));
+        const existing = comments.find(comment => parseAgent(comment.body)?.id === agent.id);
+        if (existing)
+            await this.updateComment(existing, renderAgentComment(agent));
+        else
+            await this.comment(renderAgentComment(agent));
+    }
+}

package/dist/store-task-definition.js

@@ -0,0 +1,19 @@
+function immutableTaskDefinition(task) {
+    const routing = task.routing ? {
+        provider: task.routing.provider, model: task.routing.model, profile: task.routing.profile,
+        reasoning: task.routing.reasoning, cwd: task.routing.cwd, projectId: task.routing.projectId
+    } : undefined;
+    return {
+        jobId: task.jobId, id: task.id, priority: task.priority, storySize: task.storySize ?? 'M', projectName: task.projectName, agentName: task.agentName, agentGraph: task.agentGraph,
+        kind: task.kind ?? 'work', planningDecisionId: task.planningDecisionId, planningSource: task.planningSource, planningRound: task.planningRound, parentTaskId: task.parentTaskId, dependencies: task.dependencies, capabilities: task.capabilities, workerRequirements: task.workerRequirements, workerSelection: task.workerSelection, adapter: task.adapter,
+        input: task.input, attachments: task.attachments, output: task.output, routing, chatgptTabClosePolicy: task.chatgptTabClosePolicy ?? 'after-start', continuation: task.continuation ?? null, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs
+    };
+}
+export function sameTaskDefinition(left, right) {
+    return JSON.stringify(immutableTaskDefinition(left)) === JSON.stringify(immutableTaskDefinition(right));
+}
+export function isTaskForJob(task, jobId, soleTrustedJob) {
+    if (task.jobId === jobId)
+        return true;
+    return !task.jobId && soleTrustedJob;
+}

package/dist/store.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { createSign } from 'node:crypto';
-import { parseAgent, parseJob, parseTask, renderAgentComment, renderJobBody, renderJobComment, renderTaskComment, AGENT_MARKER, JOB_MARKER, TASK_MARKER } from './markers.js';
+import { parseAgent, parseJob, parseTask, renderAgentComment, renderJobComment, renderTaskComment, AGENT_MARKER, JOB_MARKER, TASK_MARKER } from './markers.js';
+import { isTaskForJob, sameTaskDefinition } from './store-task-definition.js';
 export async function loadManagedGitHubPullRequestGraphql(client, repository, prNumber, trustedAuthors) {
     const [owner, name] = repository.split('/', 2);
     if (!owner || !name || !Number.isInteger(prNumber) || prNumber <= 0 || !client.graphql)
@@ -86,20 +87,6 @@ export class InMemoryStore {
         return [...this.values.values()].map(parseTask).filter((x) => x !== null).filter(task => isTaskForJob(task, jobId, jobs.length === 1));
     }
 }
-function immutableTaskDefinition(task) {
-    const routing = task.routing ? {
-        provider: task.routing.provider, model: task.routing.model, profile: task.routing.profile,
-        reasoning: task.routing.reasoning, cwd: task.routing.cwd, projectId: task.routing.projectId
-    } : undefined;
-    return {
-        jobId: task.jobId, id: task.id, priority: task.priority, storySize: task.storySize ?? 'M', projectName: task.projectName, agentName: task.agentName, agentGraph: task.agentGraph,
-        kind: task.kind ?? 'work', planningDecisionId: task.planningDecisionId, planningSource: task.planningSource, planningRound: task.planningRound, parentTaskId: task.parentTaskId, dependencies: task.dependencies, capabilities: task.capabilities, workerRequirements: task.workerRequirements, workerSelection: task.workerSelection, adapter: task.adapter,
-        input: task.input, attachments: task.attachments, output: task.output, routing, chatgptTabClosePolicy: task.chatgptTabClosePolicy ?? 'after-start', continuation: task.continuation ?? null, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs
-    };
-}
-function sameTaskDefinition(left, right) {
-    return JSON.stringify(immutableTaskDefinition(left)) === JSON.stringify(immutableTaskDefinition(right));
-}
 async function githubGraphql(client, query, variables) {
     if (!client.graphql)
         throw new Error('GitHub GraphQL client is required');
@@ -408,221 +395,7 @@ export class GhApiClient {
         throw new Error('gh authentication did not return a login');
     }
 }
-export class GitHubStore {
-    client;
-    repository;
-    prNumber;
-    trustedAuthors;
-    constructor(client, repository, prNumber, trustedAuthors = new Set()) {
-        this.client = client;
-        this.repository = repository;
-        this.prNumber = prNumber;
-        this.trustedAuthors = trustedAuthors;
-    }
-    isTrusted(comment) { return comment.authorLogin !== null && this.trustedAuthors.has(comment.authorLogin); }
-    repoParts() {
-        const [owner, name] = this.repository.split('/', 2);
-        if (!owner || !name)
-            throw new Error(`Invalid GitHub repository ${this.repository}`);
-        return { owner, name };
-    }
-    async graphql(query, variables) {
-        if (!this.client.graphql)
-            throw new Error('GitHub GraphQL client is required');
-        return await this.client.graphql(query, variables);
-    }
-    async prNode() {
-        const { owner, name } = this.repoParts();
-        const data = await this.graphql('query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){id state merged mergedAt closedAt body}}}', { owner, name, number: this.prNumber });
-        const repository = data.repository;
-        const pr = repository?.pullRequest;
-        if (!pr)
-            throw new Error(`Pull request #${this.prNumber} not found in ${this.repository}`);
-        return pr;
-    }
-    async pullRequestBody() {
-        const pr = await this.prNode();
-        return typeof pr.body === 'string' ? pr.body : '';
-    }
-    async list() {
-        const { owner, name } = this.repoParts();
-        const all = [];
-        let cursor = null;
-        do {
-            const data = await this.graphql('query($owner:String!,$name:String!,$number:Int!,$cursor:String){repository(owner:$owner,name:$name){pullRequest(number:$number){comments(first:100,after:$cursor){nodes{id databaseId url body updatedAt author{login}} pageInfo{hasNextPage endCursor}}}}}', { owner, name, number: this.prNumber, cursor });
-            const repository = data.repository;
-            const pr = repository?.pullRequest;
-            const comments = pr?.comments;
-            const nodes = Array.isArray(comments?.nodes) ? comments.nodes : [];
-            for (const value of nodes) {
-                const author = value.author;
-                all.push({
-                    id: Number(value.databaseId ?? 0),
-                    nodeId: typeof value.id === 'string' ? value.id : undefined,
-                    url: typeof value.url === 'string' ? value.url : undefined,
-                    body: String(value.body ?? ''),
-                    updatedAt: String(value.updatedAt ?? ''),
-                    authorLogin: typeof author?.login === 'string' ? author.login : null
-                });
-            }
-            const pageInfo = comments?.pageInfo;
-            cursor = pageInfo?.hasNextPage === true && typeof pageInfo.endCursor === 'string' ? pageInfo.endCursor : null;
-        } while (cursor);
-        return all;
-    }
-    async comments() { return this.list(); }
-    async pullRequestState() {
-        const pr = await this.prNode();
-        if (pr.merged === true || typeof pr.mergedAt === 'string')
-            return 'MERGED';
-        return String(pr.state ?? '').toUpperCase() === 'CLOSED' ? 'CLOSED' : 'OPEN';
-    }
-    async mergePullRequest(expectedHeadSha) {
-        const payload = { merge_method: 'squash' };
-        if (expectedHeadSha)
-            payload.sha = expectedHeadSha;
-        const result = await this.client.request('repos/' + this.repository + '/pulls/' + this.prNumber + '/merge', {
-            method: 'PUT',
-            body: JSON.stringify(payload),
-        });
-        if (result.merged !== true)
-            throw new Error(typeof result.message === 'string' ? result.message : 'Pull request #' + this.prNumber + ' was not merged');
-    }
-    async closePullRequest() {
-        await this.client.request('repos/' + this.repository + '/pulls/' + this.prNumber, { method: 'PATCH', body: JSON.stringify({ state: 'closed' }) });
-    }
-    async updatePullRequestBody(body) {
-        await this.client.request('repos/' + this.repository + '/pulls/' + this.prNumber, { method: 'PATCH', body: JSON.stringify({ body }) });
-    }
-    async headSha() {
-        const { owner, name } = this.repoParts();
-        const data = await this.graphql('query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){headRefOid}}}', { owner, name, number: this.prNumber });
-        const repository = data.repository;
-        const pr = repository?.pullRequest;
-        return typeof pr?.headRefOid === 'string' ? pr.headRefOid : null;
-    }
-    async load(jobId) {
-        const comments = (await this.list()).filter(comment => this.isTrusted(comment));
-        const bodyJob = parseJob(await this.pullRequestBody());
-        const commentJobs = comments.map(x => parseJob(x.body)).filter((x) => x !== null && typeof x.id === 'string' && x.id.length > 0);
-        const jobs = bodyJob ? [bodyJob] : commentJobs;
-        const job = jobs.find(x => x.id === jobId);
-        if (!job) {
-            const conflicting = bodyJob ?? commentJobs[0];
-            if (conflicting)
-                throw new Error(`JOB_ID_MISMATCH: PR #${this.prNumber} is bound to ${conflicting.id}, not ${jobId}`);
-            throw new Error(`JOB_MARKER_MISSING: Managed GitHub job ${jobId} has no durable ${JOB_MARKER} marker in PR #${this.prNumber}`);
-        }
-        const soleTrustedJob = jobs.length === 1;
-        job.tasks = comments.map(comment => {
-            const task = parseTask(comment.body);
-            if (!task)
-                return null;
-            const taskUrl = comment.url ?? (comment.id > 0 ? `https://github.com/${this.repository}/pull/${this.prNumber}#issuecomment-${comment.id}` : undefined);
-            return taskUrl ? { ...task, taskUrl } : task;
-        }).filter((x) => x !== null).filter(task => isTaskForJob(task, jobId, soleTrustedJob));
-        return job;
-    }
-    async validateJobBinding(jobId) {
-        const body = await this.pullRequestBody();
-        const bodyHasMarker = body.includes(`<!-- ${JOB_MARKER} `);
-        const bodyJob = parseJob(body);
-        if (bodyHasMarker && !bodyJob)
-            throw new Error(`JOB_MARKER_MALFORMED: PR #${this.prNumber} body contains a ${JOB_MARKER} marker that cannot be parsed`);
-        if (bodyJob) {
-            if (bodyJob.id !== jobId)
-                throw new Error(`JOB_ID_MISMATCH: PR #${this.prNumber} is bound to ${bodyJob.id}, not ${jobId}`);
-            return;
-        }
-        const comments = (await this.list()).filter(comment => this.isTrusted(comment));
-        const markerComments = comments.filter(comment => comment.body.includes(JOB_MARKER));
-        const parsed = markerComments.map(comment => parseJob(comment.body));
-        const malformed = parsed.filter(job => job === null).length;
-        if (malformed > 0)
-            throw new Error(`JOB_MARKER_MALFORMED: PR #${this.prNumber} contains ${malformed} trusted ${JOB_MARKER} marker(s) that cannot be parsed`);
-        const jobs = parsed.filter((job) => job !== null);
-        const matches = jobs.filter(job => job.id === jobId);
-        if (matches.length === 0) {
-            if (jobs.length > 0)
-                throw new Error(`JOB_ID_MISMATCH: PR #${this.prNumber} is bound to ${jobs.map(job => job.id).join(', ')}, not ${jobId}`);
-            throw new Error(`JOB_MARKER_MISSING: Managed GitHub job ${jobId} has no durable ${JOB_MARKER} marker in PR #${this.prNumber}`);
-        }
-        if (matches.length > 1)
-            throw new Error(`JOB_MARKER_DUPLICATED: PR #${this.prNumber} contains ${matches.length} trusted ${JOB_MARKER} markers for job ${jobId}`);
-        if (jobs.length > 1)
-            throw new Error(`JOB_BINDING_CONFLICT: PR #${this.prNumber} contains trusted ${JOB_MARKER} markers for multiple job ids`);
-    }
-    async listAgents() { return (await this.list()).filter(comment => this.isTrusted(comment)).map(x => parseAgent(x.body)).filter((x) => x !== null); }
-    async comment(body) {
-        const pr = await this.prNode();
-        await this.graphql('mutation($subjectId:ID!,$body:String!){addComment(input:{subjectId:$subjectId,body:$body}){commentEdge{node{id}}}}', { subjectId: pr.id, body });
-    }
-    async updateComment(comment, body) {
-        if (!comment.nodeId)
-            throw new Error('GitHub comment node id is required for GraphQL update');
-        await this.graphql('mutation($id:ID!,$body:String!){updateIssueComment(input:{id:$id,body:$body}){issueComment{id}}}', { id: comment.nodeId, body });
-    }
-    async deleteComment(comment) {
-        if (!comment.nodeId)
-            throw new Error('GitHub comment node id is required for GraphQL delete');
-        await this.graphql('mutation($id:ID!){deleteIssueComment(input:{id:$id}){clientMutationId}}', { id: comment.nodeId });
-    }
-    async saveJob(job) {
-        const currentBody = await this.pullRequestBody();
-        const bodyJob = parseJob(currentBody);
-        if (bodyJob && bodyJob.id !== job.id)
-            throw new Error(`PR #${this.prNumber} body already has a different ${JOB_MARKER} marker`);
-        const comments = (await this.list()).filter(comment => this.isTrusted(comment));
-        const jobComments = comments.filter(comment => parseJob(comment.body) !== null);
-        const conflicts = jobComments.filter(comment => parseJob(comment.body)?.id !== job.id);
-        if (conflicts.length > 0)
-            throw new Error(`PR #${this.prNumber} already has a different ${JOB_MARKER} marker`);
-        await this.updatePullRequestBody(renderJobBody(job));
-        const persisted = parseJob(await this.pullRequestBody());
-        if (!persisted || persisted.id !== job.id)
-            throw new Error(`Failed to persist ${JOB_MARKER} marker in PR #${this.prNumber} body for job ${job.id}`);
-        for (const legacy of jobComments.filter(comment => parseJob(comment.body)?.id === job.id))
-            await this.deleteComment(legacy);
-    }
-    async appendTask(task) {
-        if (!task.jobId)
-            throw new Error('GitHub task requires jobId');
-        await this.load(task.jobId);
-        const comments = (await this.list()).filter(comment => this.isTrusted(comment));
-        const matches = comments.filter(comment => {
-            const existing = parseTask(comment.body);
-            return existing !== null && existing.jobId === task.jobId && existing.id === task.id;
-        });
-        if (matches.length === 0) {
-            await this.comment(renderTaskComment(task));
-            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`);
-        for (const duplicate of parsed.slice(1))
-            await this.deleteComment(duplicate.comment);
-    }
-    async saveTask(task) {
-        const comments = (await this.list()).filter(comment => this.isTrusted(comment));
-        const existing = comments.filter(comment => { const markerTask = parseTask(comment.body); return markerTask !== null && markerTask.jobId === task.jobId && markerTask.id === task.id; });
-        if (existing.length > 0) {
-            await this.updateComment(existing[0], renderTaskComment(task));
-            for (const duplicate of existing.slice(1))
-                await this.deleteComment(duplicate);
-        }
-        else
-            await this.appendTask(task);
-    }
-    async saveAgent(agent) {
-        const comments = (await this.list()).filter(comment => this.isTrusted(comment));
-        const existing = comments.find(comment => parseAgent(comment.body)?.id === agent.id);
-        if (existing)
-            await this.updateComment(existing, renderAgentComment(agent));
-        else
-            await this.comment(renderAgentComment(agent));
-    }
-}
+export { GitHubStore } from './store-github.js';
 export async function listManagedGitHubJobs(client, repository, trustedAuthors) {
     if (!client.graphql)
         throw new Error('GitHub GraphQL client is required');
@@ -681,8 +454,3 @@ export async function listManagedGitHubJobs(client, repository, trustedAuthors)
     } while (cursor);
     return output.sort((a, b) => b.job.prNumber - a.job.prNumber);
 }
-function isTaskForJob(task, jobId, soleTrustedJob) {
-    if (task.jobId === jobId)
-        return true;
-    return !task.jobId && soleTrustedJob;
-}

package/dist/workflow/contracts.js

@@ -0,0 +1,84 @@
+export const WORKFLOW_EVENT_NAMES = [
+    'activate',
+    'block',
+    'cancel',
+    'dispatch',
+    'effect.cancelActiveTasks.failed',
+    'effect.launchTask.failed',
+    'effect.mergePullRequest.failed',
+    'fail',
+    'hold',
+    'implementation.completed',
+    'pr.closed',
+    'pr.merged',
+    'reconcile',
+    'reconcile.blocked',
+    'reconcile.completed',
+    'reconcile.started',
+    'release',
+    'retry',
+    'review.approved',
+    'task.blocked',
+    'task.cancelled',
+    'task.completed',
+    'task.failed',
+    'task.started',
+];
+export const WORKFLOW_FACT_NAMES = [
+    'dependenciesSatisfied',
+    'dependenciesUnsatisfied',
+    'runnable',
+    'dispatchable',
+    'notMerged',
+    'autoMerge',
+];
+export const WORKFLOW_MUTATION_NAMES = [
+    'mutation.clearError',
+    'mutation.clearFailureReason',
+];
+export const WORKFLOW_EFFECT_NAMES = [
+    'effect.launchTask',
+    'effect.cancelActiveTasks',
+    'effect.mergePullRequest',
+];
+export const WORKFLOW_EFFECT_POLICIES = {
+    'effect.launchTask': {
+        idempotency: 'job-task-attempt',
+        failureEvent: 'effect.launchTask.failed',
+        retry: 'workflow',
+        observability: 'workflow.effect',
+    },
+    'effect.cancelActiveTasks': {
+        idempotency: 'job-transition',
+        failureEvent: 'effect.cancelActiveTasks.failed',
+        retry: 'workflow',
+        observability: 'workflow.effect',
+    },
+    'effect.mergePullRequest': {
+        idempotency: 'job-head-sha',
+        failureEvent: 'effect.mergePullRequest.failed',
+        retry: 'workflow',
+        observability: 'workflow.effect',
+    },
+};
+export function workflowEffectFailureEvent(effect) {
+    return WORKFLOW_EFFECT_POLICIES[effect].failureEvent;
+}
+const mutations = new Set(WORKFLOW_MUTATION_NAMES);
+const effects = new Set(WORKFLOW_EFFECT_NAMES);
+export function classifyWorkflowActions(actions) {
+    const foundMutations = [];
+    const foundEffects = [];
+    for (const action of actions) {
+        if (mutations.has(action))
+            foundMutations.push(action);
+        else if (effects.has(action))
+            foundEffects.push(action);
+        else
+            throw new Error(`Unknown canonical workflow action ${action}`);
+    }
+    return { mutations: foundMutations, effects: foundEffects };
+}
+export function emptyWorkflowDecision(reason) {
+    return { accepted: false, target: null, guard: null, actions: [], mutations: [], effects: [], reason };
+}