agents-relay 1.0.0

package/dist/scheduler.js

@@ -0,0 +1,49 @@
+import { assertJobTransition, assertTaskTransition } from './types.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); }
+export function completionGateSatisfied(job) {
+    if (job.executionMode !== 'autonomous')
+        return true;
+    const planners = job.tasks.filter(task => task.kind === 'planner');
+    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);
+    if (job.tasks.length === 0) {
+        if (job.executionMode === 'autonomous' && job.state !== 'WAITING') {
+            assertJobTransition(job.state, 'WAITING');
+            job.state = 'WAITING';
+            job.updatedAt = new Date().toISOString();
+        }
+        return job;
+    }
+    const map = new Map(job.tasks.map(t => [t.id, t]));
+    for (const task of job.tasks) {
+        if (['QUEUED', 'WAITING'].includes(task.state) && dependencyReady(task, map))
+            transitionTask(task, 'READY');
+    }
+    const active = job.tasks.some(t => ['READY', 'RUNNING'].includes(t.state));
+    const blocked = job.tasks.some(t => t.state === 'BLOCKED');
+    const waiting = job.tasks.some(t => ['QUEUED', 'WAITING'].includes(t.state));
+    const failed = job.tasks.some(t => t.state === 'FAILED');
+    const cancelled = job.tasks.every(t => t.state === 'CANCELLED');
+    const next = failed ? 'FAILED' : active ? 'RUNNING' : blocked ? 'BLOCKED' : waiting ? 'WAITING' : cancelled ? 'CANCELLED' : completionGateSatisfied(job) ? 'COMPLETED' : 'WAITING';
+    if (job.state !== next) {
+        assertJobTransition(job.state, next);
+        job.state = next;
+        job.updatedAt = new Date().toISOString();
+    }
+    return job;
+}
+export function extendRetryBudget(task, windowSize = 3) {
+    if (!Number.isInteger(windowSize) || windowSize < 1)
+        throw new Error('Retry window size must be a positive integer');
+    const usedOrBudgeted = Math.max(task.maxAttempts, task.attempt);
+    return Math.max(windowSize, (Math.floor(usedOrBudgeted / windowSize) + 1) * windowSize);
+}
+export function transitionTask(task, state) { assertTaskTransition(task.state, state); task.state = state; if (['READY', 'RUNNING', 'SUCCEEDED'].includes(state))
+    task.error = null; task.updatedAt = new Date().toISOString(); }

package/dist/store.js

@@ -0,0 +1,586 @@
+import { spawn } from 'node:child_process';
+import { createSign } from 'node:crypto';
+import { parseAgent, parseJob, parseTask, renderAgentComment, renderJobComment, renderTaskComment, AGENT_MARKER, JOB_MARKER, TASK_MARKER } from './markers.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)
+        return [];
+    const query = 'query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){state isDraft merged mergedAt closedAt body comments(last:100){nodes{author{login} body}}}}}';
+    const data = await client.graphql(query, { owner, name, number: prNumber });
+    const repo = data.repository;
+    const pr = repo?.pullRequest;
+    if (!pr)
+        return [];
+    const comments = pr.comments?.nodes;
+    const trusted = (Array.isArray(comments) ? comments : []).filter(item => {
+        const row = item;
+        const author = row.author;
+        return typeof author?.login === 'string' && trustedAuthors.has(author.login);
+    });
+    const jobs = trusted.map(item => parseJob(String(item.body ?? ''))).filter((item) => item !== null);
+    const tasks = trusted.map(item => parseTask(String(item.body ?? ''))).filter((item) => item !== null);
+    const state = String(pr.state ?? '').toUpperCase();
+    const githubState = pr.merged === true ? 'MERGED' : state === 'CLOSED' ? 'CLOSED' : 'OPEN';
+    return jobs.map(job => {
+        job.tasks = tasks.filter(task => task.jobId === job.id || (!task.jobId && jobs.length === 1));
+        if (!job.description && typeof pr.body === 'string' && pr.body)
+            job.description = pr.body;
+        return { job, githubState, draft: pr.isDraft === true, mergedAt: typeof pr.mergedAt === 'string' ? pr.mergedAt : null, closedAt: typeof pr.closedAt === 'string' ? pr.closedAt : null };
+    });
+}
+export async function loadManagedGitHubJobGraphql(client, repository, prNumber, jobId, trustedAuthors) {
+    return (await loadManagedGitHubPullRequestGraphql(client, repository, prNumber, trustedAuthors)).find(item => item.job.id === jobId) ?? null;
+}
+const COMPLETED_JOB_HISTORY_LIMIT = 10;
+function isCompletedManagedJob(item) { return ['COMPLETED', 'CANCELLED'].includes(item.job.state) || item.githubState !== 'OPEN'; }
+function completedAt(item) { return item.mergedAt ?? item.closedAt ?? item.job.updatedAt; }
+export function dashboardManagedJobs(items) {
+    const unfinished = items.filter(item => !isCompletedManagedJob(item));
+    const completed = items.filter(isCompletedManagedJob).sort((a, b) => completedAt(b).localeCompare(completedAt(a)) || b.job.prNumber - a.job.prNumber).slice(0, COMPLETED_JOB_HISTORY_LIMIT);
+    return [...unfinished, ...completed];
+}
+export class InMemoryStore {
+    values = new Map();
+    constructor(job) {
+        if (job) {
+            this.values.set(`${JOB_MARKER}:${job.id}`, renderJobComment(job));
+            for (const task of job.tasks)
+                this.values.set(`${TASK_MARKER}:${task.jobId ?? ''}:${task.id}`, renderTaskComment(task));
+        }
+    }
+    async load(jobId) { const job = await this.findJob(jobId); if (!job)
+        throw new Error(`Job ${jobId} not found`); job.tasks = this.tasksForJob(jobId); return job; }
+    async saveJob(job) { this.values.set(`${JOB_MARKER}:${job.id}`, renderJobComment(job)); }
+    async appendTask(task) {
+        const key = `${TASK_MARKER}:${task.jobId ?? ''}:${task.id}`;
+        const existing = this.values.get(key);
+        if (existing) {
+            const current = parseTask(existing);
+            if (current && sameTaskDefinition(current, task))
+                return;
+            throw new Error(`Task ${task.id} already exists with a different definition`);
+        }
+        this.values.set(key, renderTaskComment(task));
+    }
+    async saveTask(task) { this.values.set(`${TASK_MARKER}:${task.jobId ?? ''}:${task.id}`, renderTaskComment(task)); }
+    async listAgents() { return [...this.values.values()].map(parseAgent).filter((x) => x !== null); }
+    async saveAgent(agent) { this.values.set(`${AGENT_MARKER}:${agent.id}`, renderAgentComment(agent)); }
+    async comments() { return [...this.values.values()].map((body, i) => ({ id: i + 1, body, updatedAt: new Date().toISOString(), authorLogin: 'local' })); }
+    findJob(jobId) { return [...this.values.values()].map(parseJob).find((x) => x !== null && x.id === jobId) ?? null; }
+    tasksForJob(jobId) {
+        const jobs = [...this.values.values()].map(parseJob).filter((x) => x !== null && typeof x.id === 'string' && x.id.length > 0);
+        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, projectName: task.projectName, agentName: task.agentName,
+        kind: task.kind ?? 'work', parentTaskId: task.parentTaskId, dependencies: task.dependencies, capabilities: task.capabilities, adapter: task.adapter,
+        input: task.input, routing, 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');
+    return await client.graphql(query, variables);
+}
+function repositoryParts(repository) {
+    const [owner, name] = repository.split('/', 2);
+    if (!owner || !name)
+        throw new Error(`Invalid GitHub repository ${repository}`);
+    return { owner, name };
+}
+async function headHasNoAheadCommits(client, repository, base, head) {
+    const path = `repos/${repository}/compare/${encodeURIComponent(base)}...${encodeURIComponent(head)}`;
+    const comparison = await client.request(path);
+    return Number(comparison.ahead_by) === 0;
+}
+async function bootstrapEmptyHeadCommit(client, repository, head) {
+    const { owner, name } = repositoryParts(repository);
+    const data = await githubGraphql(client, 'query($owner:String!,$name:String!,$qualified:String!){repository(owner:$owner,name:$name){ref(qualifiedName:$qualified){target{... on Commit{oid tree{oid}}}}}}', { owner, name, qualified: `refs/heads/${head}` });
+    const repo = data.repository;
+    const ref = repo?.ref;
+    const target = ref?.target;
+    const tree = target?.tree;
+    const expectedHeadOid = typeof target?.oid === 'string' ? target.oid : '';
+    const treeOid = typeof tree?.oid === 'string' ? tree.oid : '';
+    if (!expectedHeadOid || !treeOid)
+        throw new Error(`Unable to resolve head branch ${head}`);
+    const created = await client.request(`repos/${repository}/git/commits`, {
+        method: 'POST',
+        body: JSON.stringify({
+            message: 'chore: bootstrap Agents Relay job',
+            tree: treeOid,
+            parents: [expectedHeadOid],
+        }),
+    });
+    const commitOid = typeof created.sha === 'string' ? created.sha : '';
+    if (!commitOid)
+        throw new Error(`Unable to create bootstrap commit for ${head}`);
+    await client.request(`repos/${repository}/git/refs/heads/${head}`, {
+        method: 'PATCH',
+        body: JSON.stringify({ sha: commitOid, force: false }),
+    });
+}
+function pullRequest(value) {
+    const item = value;
+    const head = item.head;
+    const base = item.base;
+    const number = Number(item.number);
+    const headRef = typeof item.headRefName === 'string' ? item.headRefName : typeof head?.ref === 'string' ? head.ref : '';
+    const baseRef = typeof item.baseRefName === 'string' ? item.baseRefName : typeof base?.ref === 'string' ? base.ref : '';
+    if (!Number.isInteger(number) || number <= 0 || !headRef || !baseRef)
+        throw new Error('Invalid GitHub pull request response');
+    return { number, title: String(item.title ?? ''), body: String(item.body ?? ''), state: String(item.state ?? ''), head: headRef, base: baseRef };
+}
+export async function resolvePullRequest(client, repository, options) {
+    const { owner, name } = repositoryParts(repository);
+    if (options.prNumber) {
+        const data = await githubGraphql(client, 'query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){number title body state headRefName baseRefName}}}', { owner, name, number: options.prNumber });
+        const repo = data.repository;
+        const pr = repo?.pullRequest;
+        if (!pr)
+            throw new Error(`Pull request #${options.prNumber} not found`);
+        return pullRequest(pr);
+    }
+    if (!options.head)
+        throw new Error('--head is required when --pr is not provided');
+    const base = options.base || 'main';
+    const find = async () => {
+        const data = await githubGraphql(client, 'query($owner:String!,$name:String!,$head:String!,$base:String!){repository(owner:$owner,name:$name){pullRequests(first:20,states:OPEN,headRefName:$head,baseRefName:$base){nodes{number title body state headRefName baseRefName}}}}', { owner, name, head: options.head, base });
+        const repo = data.repository;
+        const connection = repo?.pullRequests;
+        const nodes = Array.isArray(connection?.nodes) ? connection.nodes : [];
+        const match = nodes.map(pullRequest).find(pr => pr.head === options.head && pr.base === base);
+        return match ?? null;
+    };
+    const existing = await find();
+    if (existing)
+        return existing;
+    if (!options.title)
+        throw new Error('--title is required when creating a pull request');
+    if (await headHasNoAheadCommits(client, repository, base, options.head)) {
+        await bootstrapEmptyHeadCommit(client, repository, options.head);
+        const afterBootstrap = await find();
+        if (afterBootstrap)
+            return afterBootstrap;
+    }
+    const repositoryData = await githubGraphql(client, 'query($owner:String!,$name:String!){repository(owner:$owner,name:$name){id}}', { owner, name });
+    const repo = repositoryData.repository;
+    if (typeof repo?.id !== 'string')
+        throw new Error(`Repository ${repository} not found`);
+    const create = async () => {
+        const data = await githubGraphql(client, 'mutation($repositoryId:ID!,$base:String!,$head:String!,$title:String!,$body:String!){createPullRequest(input:{repositoryId:$repositoryId,baseRefName:$base,headRefName:$head,title:$title,body:$body}){pullRequest{number title body state headRefName baseRefName}}}', { repositoryId: repo.id, base, head: options.head, title: options.title, body: options.body ?? '' });
+        const result = data.createPullRequest;
+        if (!result?.pullRequest)
+            throw new Error('GitHub createPullRequest returned no pull request');
+        return pullRequest(result.pullRequest);
+    };
+    try {
+        return await create();
+    }
+    catch (error) {
+        const raced = await find();
+        if (raced)
+            return raced;
+        const message = error instanceof Error ? error.message : String(error);
+        if (/No commits between|no commits between/i.test(message)) {
+            await bootstrapEmptyHeadCommit(client, repository, options.head);
+            const afterBootstrap = await find();
+            if (afterBootstrap)
+                return afterBootstrap;
+            return create();
+        }
+        throw error;
+    }
+}
+function base64Url(value) {
+    return Buffer.from(value).toString('base64url');
+}
+export function createGitHubAppJwt(options, now = Math.floor(Date.now() / 1000)) {
+    const header = base64Url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
+    const payload = base64Url(JSON.stringify({ iat: now - 60, exp: now + 540, iss: options.appId }));
+    const unsigned = `${header}.${payload}`;
+    const signer = createSign('RSA-SHA256');
+    signer.update(unsigned);
+    signer.end();
+    return `${unsigned}.${signer.sign(options.privateKey).toString('base64url')}`;
+}
+export class GhApiClient {
+    appAuth;
+    cooldownUntil = 0;
+    rateLimitFailures = 0;
+    installationToken = null;
+    constructor(appAuth = null) {
+        this.appAuth = appAuth;
+    }
+    rateLimitStatus() {
+        const limited = Date.now() < this.cooldownUntil;
+        return { limited, cooldownUntil: limited ? new Date(this.cooldownUntil).toISOString() : null };
+    }
+    assertAvailable() {
+        if (Date.now() < this.cooldownUntil)
+            throw new Error(`GitHub API cooldown active until ${new Date(this.cooldownUntil).toISOString()}`);
+    }
+    noteFailure(message) {
+        if (!/rate limit|secondary rate|HTTP 429/i.test(message))
+            return;
+        this.rateLimitFailures += 1;
+        const delay = Math.min(15 * 60_000, 60_000 * (2 ** Math.min(this.rateLimitFailures - 1, 4)));
+        this.cooldownUntil = Date.now() + delay;
+    }
+    noteSuccess() { if (Date.now() >= this.cooldownUntil)
+        this.rateLimitFailures = 0; }
+    appJwt(now = Math.floor(Date.now() / 1000)) {
+        if (!this.appAuth)
+            throw new Error('GitHub App authentication is not configured');
+        return createGitHubAppJwt(this.appAuth, now);
+    }
+    async appRequest(path, method = 'GET') {
+        const response = await fetch(`https://api.github.com${path}`, {
+            method,
+            headers: {
+                accept: 'application/vnd.github+json',
+                authorization: `Bearer ${this.appJwt()}`,
+                'x-github-api-version': '2026-03-10',
+                'user-agent': 'agents-relay',
+            },
+        });
+        const text = await response.text();
+        if (!response.ok)
+            throw new Error(`GitHub App API ${response.status}: ${text}`);
+        return JSON.parse(text);
+    }
+    async installationAccessToken() {
+        if (!this.appAuth)
+            throw new Error('GitHub App authentication is not configured');
+        if (this.installationToken && this.installationToken.expiresAt - Date.now() > 5 * 60_000)
+            return this.installationToken.value;
+        const parsed = await this.appRequest(`/app/installations/${this.appAuth.installationId}/access_tokens`, 'POST');
+        const token = typeof parsed.token === 'string' ? parsed.token : '';
+        const expiresAt = typeof parsed.expires_at === 'string' ? Date.parse(parsed.expires_at) : 0;
+        if (!token || !Number.isFinite(expiresAt) || expiresAt <= Date.now())
+            throw new Error('GitHub App installation token response was invalid');
+        this.installationToken = { value: token, expiresAt };
+        return token;
+    }
+    async commandEnv() {
+        if (!this.appAuth)
+            return process.env;
+        const token = await this.installationAccessToken();
+        return { ...process.env, GH_TOKEN: token, GITHUB_TOKEN: token };
+    }
+    async spawnGh(args, input, env = process.env, rateLimited = true) {
+        if (rateLimited)
+            this.assertAvailable();
+        return new Promise((resolve, reject) => {
+            const child = spawn('gh', args, { env });
+            let stdout = '';
+            let stderr = '';
+            child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+            child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+            child.on('error', reject);
+            if (input !== undefined)
+                child.stdin.write(input);
+            child.stdin.end();
+            child.on('close', code => {
+                if (code !== 0) {
+                    const message = stderr.trim() || `gh exited ${code}`;
+                    if (rateLimited)
+                        this.noteFailure(message);
+                    reject(new Error(message));
+                    return;
+                }
+                if (rateLimited)
+                    this.noteSuccess();
+                resolve(stdout);
+            });
+        });
+    }
+    async graphql(query, variables = {}) {
+        this.assertAvailable();
+        const payload = JSON.stringify({ query, variables });
+        const stdout = await this.spawnGh(['api', 'graphql', '--input', '-'], payload, await this.commandEnv());
+        const parsed = JSON.parse(stdout);
+        if (Array.isArray(parsed.errors) && parsed.errors.length > 0) {
+            const message = JSON.stringify(parsed.errors);
+            this.noteFailure(message);
+            throw new Error(message);
+        }
+        return parsed.data ?? parsed;
+    }
+    async request(path, init = {}) {
+        this.assertAvailable();
+        const args = ['api', path];
+        const method = String(init.method ?? 'GET');
+        if (method !== 'GET')
+            args.push('--method', method);
+        if (init.body)
+            args.push('--input', '-');
+        const stdout = await this.spawnGh(args, init.body ? String(init.body) : undefined, await this.commandEnv());
+        if (!stdout.trim())
+            return null;
+        try {
+            return JSON.parse(stdout);
+        }
+        catch {
+            return stdout;
+        }
+    }
+    async localLogin() {
+        return new Promise((resolve) => {
+            const child = spawn('gh', ['auth', 'status', '--active', '--json', 'hosts']);
+            let stdout = '';
+            child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+            child.on('error', () => resolve(null));
+            child.on('close', () => {
+                try {
+                    const value = JSON.parse(stdout);
+                    const hosts = value.hosts;
+                    const github = hosts?.['github.com'];
+                    const active = Array.isArray(github) ? github.find(item => item.active === true) : undefined;
+                    resolve(typeof active?.login === 'string' && active.login.length > 0 ? active.login : null);
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        });
+    }
+    async currentLogin() {
+        if (this.appAuth) {
+            const app = await this.appRequest('/app');
+            if (typeof app.slug === 'string' && app.slug.length > 0)
+                return `${app.slug}[bot]`;
+            throw new Error('GitHub App identity lookup returned no slug');
+        }
+        else {
+            const local = await this.localLogin();
+            if (local)
+                return local;
+            try {
+                const value = await this.graphql('query { viewer { login } }');
+                const viewer = value.viewer;
+                if (typeof viewer?.login === 'string' && viewer.login.length > 0)
+                    return viewer.login;
+            }
+            catch { /* handled below */ }
+        }
+        const local = await this.localLogin();
+        if (local)
+            return local;
+        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}}}', { 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 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 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,
+                    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 load(jobId) {
+        const comments = (await this.list()).filter(comment => this.isTrusted(comment));
+        const jobs = comments.map(x => parseJob(x.body)).filter((x) => x !== null && typeof x.id === 'string' && x.id.length > 0);
+        const job = jobs.find(x => x.id === jobId);
+        if (!job)
+            throw new Error(`Managed GitHub job ${jobId} has no durable ${JOB_MARKER} marker in PR #${this.prNumber}; run agents-relay job adopt --repo ${this.repository} --pr ${this.prNumber} --id ${jobId}`);
+        const soleTrustedJob = jobs.length === 1;
+        job.tasks = comments.map(x => parseTask(x.body)).filter((x) => x !== null).filter(task => isTaskForJob(task, jobId, soleTrustedJob));
+        return job;
+    }
+    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 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`);
+        const matches = jobComments.filter(comment => parseJob(comment.body)?.id === job.id);
+        if (matches.length === 0)
+            await this.comment(renderJobComment(job));
+        else {
+            await this.updateComment(matches[0], renderJobComment(job));
+            for (const duplicate of matches.slice(1))
+                await this.deleteComment(duplicate);
+        }
+        const durable = (await this.list()).filter(comment => this.isTrusted(comment)).filter(comment => parseJob(comment.body)?.id === job.id);
+        if (durable.length !== 1)
+            throw new Error(`Failed to persist exactly one ${JOB_MARKER} marker for job ${job.id}`);
+    }
+    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 async function listManagedGitHubJobs(client, repository, trustedAuthors) {
+    if (!client.graphql)
+        throw new Error('GitHub GraphQL client is required');
+    const [owner, name] = repository.split('/', 2);
+    if (!owner || !name)
+        throw new Error(`Invalid GitHub repository ${repository}`);
+    const output = [];
+    const seen = new Set();
+    const collect = (nodes) => {
+        for (const pr of nodes) {
+            const number = Number(pr.number);
+            if (!Number.isInteger(number) || number <= 0 || seen.has(number))
+                continue;
+            seen.add(number);
+            const comments = pr.comments;
+            const rows = Array.isArray(comments?.nodes) ? comments.nodes : [];
+            const trusted = rows.filter(item => {
+                const author = item.author;
+                return typeof author?.login === 'string' && trustedAuthors.has(author.login);
+            });
+            const jobs = trusted.map(item => parseJob(String(item.body ?? ''))).filter((item) => item !== null);
+            const tasks = trusted.map(item => parseTask(String(item.body ?? ''))).filter((item) => item !== null);
+            const state = String(pr.state ?? '').toUpperCase();
+            const githubState = pr.merged === true || state === 'MERGED' ? 'MERGED' : state === 'CLOSED' ? 'CLOSED' : 'OPEN';
+            for (const job of jobs) {
+                if (!job.description && typeof pr.body === 'string' && pr.body)
+                    job.description = pr.body;
+                job.prNumber = number;
+                job.repository = repository;
+                job.tasks = tasks.filter(task => task.jobId === job.id || (!task.jobId && jobs.length === 1));
+                output.push({ job, githubState, draft: pr.isDraft === true, mergedAt: typeof pr.mergedAt === 'string' ? pr.mergedAt : null, closedAt: typeof pr.closedAt === 'string' ? pr.closedAt : null });
+            }
+        }
+    };
+    let cursor = null;
+    let firstPage = true;
+    do {
+        const query = firstPage
+            ? 'query($owner:String!,$name:String!,$cursor:String){repository(owner:$owner,name:$name){open:pullRequests(first:50,after:$cursor,states:OPEN,orderBy:{field:UPDATED_AT,direction:DESC}){nodes{number body state isDraft merged mergedAt closedAt comments(first:100){nodes{author{login} body}}} pageInfo{hasNextPage endCursor}} recentClosed:pullRequests(first:20,states:CLOSED,orderBy:{field:UPDATED_AT,direction:DESC}){nodes{number body state isDraft merged mergedAt closedAt comments(first:100){nodes{author{login} body}}}}}}'
+            : 'query($owner:String!,$name:String!,$cursor:String){repository(owner:$owner,name:$name){open:pullRequests(first:50,after:$cursor,states:OPEN,orderBy:{field:UPDATED_AT,direction:DESC}){nodes{number body state isDraft merged mergedAt closedAt comments(first:100){nodes{author{login} body}}} pageInfo{hasNextPage endCursor}}}}';
+        const data = await client.graphql(query, { owner, name, cursor });
+        const repo = data.repository;
+        const open = repo?.open;
+        collect(Array.isArray(open?.nodes) ? open.nodes : []);
+        if (firstPage) {
+            const recentClosed = repo?.recentClosed;
+            collect(Array.isArray(recentClosed?.nodes) ? recentClosed.nodes : []);
+        }
+        const pageInfo = open?.pageInfo;
+        cursor = pageInfo?.hasNextPage === true && typeof pageInfo.endCursor === 'string' ? pageInfo.endCursor : null;
+        firstPage = false;
+    } 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/types.js

@@ -0,0 +1,6 @@
+const jobTransitions = { OPEN: ['RUNNING', 'WAITING', 'BLOCKED', 'COMPLETED', 'CANCELLED'], RUNNING: ['OPEN', 'WAITING', 'BLOCKED', 'COMPLETED', 'FAILED', 'CANCELLED'], WAITING: ['RUNNING', 'BLOCKED', 'COMPLETED', 'CANCELLED'], BLOCKED: ['RUNNING', 'CANCELLED'], COMPLETED: ['RUNNING', 'CANCELLED'], FAILED: ['RUNNING', 'CANCELLED'], CANCELLED: ['RUNNING'] };
+const taskTransitions = { QUEUED: ['READY', 'BLOCKED', 'CANCELLED'], READY: ['RUNNING', 'BLOCKED', 'FAILED', 'CANCELLED'], RUNNING: ['WAITING', 'BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED', 'READY'], WAITING: ['READY', 'BLOCKED', 'CANCELLED'], BLOCKED: ['READY', 'CANCELLED'], SUCCEEDED: [], FAILED: ['READY', 'CANCELLED'], CANCELLED: [] };
+export function assertJobTransition(from, to) { if (from !== to && !jobTransitions[from].includes(to))
+    throw new Error(`Invalid job transition ${from} -> ${to}`); }
+export function assertTaskTransition(from, to) { if (from !== to && !taskTransitions[from].includes(to))
+    throw new Error(`Invalid task transition ${from} -> ${to}`); }