agents-relay 1.0.0

package/dist/reconciler.js

@@ -0,0 +1,434 @@
+import { randomUUID } from 'node:crypto';
+import { schedule, transitionTask } from './scheduler.js';
+import { eventFor } from './events.js';
+import { parsePlannerResult, plannerInput } from './planner.js';
+const PRIORITY_RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
+export function compareTaskPriority(a, b, jobPriority = 'P2') { const ar = PRIORITY_RANK[a.priority ?? jobPriority]; const br = PRIORITY_RANK[b.priority ?? jobPriority]; return ar - br || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
+export function managedWorkerInput(job, task) {
+    if (!['codex', 'chatgpt'].includes(task.adapter) || !job.repository || job.prNumber <= 0)
+        return task.input;
+    const prUrl = `https://github.com/${job.repository}/pull/${job.prNumber}`;
+    return `[Agents Relay managed task]\nPR: ${prUrl}\nJob: ${job.id}\nTask: ${task.id}\nParent task: ${task.parentTaskId ?? 'none'}\nProject: ${task.projectName ?? 'unspecified'}\n\n${task.input}`;
+}
+export class Reconciler {
+    store;
+    options;
+    live = new Map();
+    plannerLive = new Map();
+    continuationLive = new Set();
+    reconciling = false;
+    constructor(store, options) {
+        this.store = store;
+        this.options = options;
+    }
+    async watch(jobId) { if (!this.options.eventBus)
+        return async () => { }; try {
+        return await this.options.eventBus.subscribe(jobId, async (event) => { if (event.type !== 'job.wake' && event.type !== 'github.webhook')
+            return; await this.reconcile(jobId); });
+    }
+    catch (error) {
+        await this.reportTransportFailure(error);
+        return async () => { };
+    } }
+    async idle() { while (this.live.size > 0 || this.plannerLive.size > 0 || this.continuationLive.size > 0 || this.reconciling)
+        await new Promise(resolve => setTimeout(resolve, 25)); }
+    async wake(jobId) { return this.reconcile(jobId); }
+    async reconcile(jobId) {
+        if (this.reconciling)
+            return this.store.load(jobId);
+        this.reconciling = true;
+        try {
+            const job = await this.store.load(jobId);
+            const previousState = job.state;
+            const prState = await this.store.pullRequestState?.() ?? 'OPEN';
+            const now = (this.options.now ?? new Date()).getTime();
+            await this.recoverFinishedWorkers(job);
+            if (prState !== 'OPEN') {
+                const reason = prState === 'MERGED' ? 'Pull request merged' : 'Pull request closed';
+                for (const task of job.tasks.filter(item => !['SUCCEEDED', 'FAILED', 'CANCELLED'].includes(item.state))) {
+                    this.live.get(task.id)?.execution.cancel();
+                    this.plannerLive.get(task.id)?.controller.abort();
+                    transitionTask(task, 'CANCELLED');
+                    task.error = reason;
+                    task.leaseOwner = null;
+                    task.leaseExpiresAt = null;
+                    await this.store.saveTask(task);
+                }
+            }
+            await this.recoverLostExecutions(job, now);
+            for (const task of job.tasks)
+                if (task.state === 'CANCELLED') {
+                    this.live.get(task.id)?.execution.cancel();
+                    this.plannerLive.get(task.id)?.controller.abort();
+                }
+            let scheduled = schedule(await this.store.load(jobId));
+            if (prState === 'OPEN' && scheduled.executionMode === 'autonomous') {
+                scheduled = schedule(await this.maybeCreatePlanner(scheduled));
+            }
+            if (prState === 'MERGED') {
+                scheduled.state = 'COMPLETED';
+                scheduled.updatedAt = new Date().toISOString();
+            }
+            if (prState === 'CLOSED') {
+                scheduled.state = 'CANCELLED';
+                scheduled.updatedAt = new Date().toISOString();
+            }
+            if (scheduled.state !== previousState)
+                await this.store.saveJob(scheduled);
+            if (prState === 'OPEN') {
+                for (const task of scheduled.tasks.filter(item => item.state === 'SUCCEEDED' && (item.continuation || scheduled.continuation) && !item.continuationDeliveredAt))
+                    this.detach(this.deliverContinuation(scheduled, task), scheduled.id, task.id, 'continuation');
+                const capacity = Math.max(0, (this.options.maxConcurrent ?? 4) - this.live.size - this.plannerLive.size);
+                for (const task of scheduled.tasks.filter(t => t.state === 'READY').sort((a, b) => compareTaskPriority(a, b, scheduled.priority ?? 'P2')).slice(0, capacity)) {
+                    if (task.kind === 'planner')
+                        await this.launchPlanner(scheduled, task);
+                    else
+                        await this.launch(scheduled, task);
+                }
+            }
+            const finalState = schedule(await this.store.load(jobId));
+            if (prState === 'MERGED') {
+                finalState.state = 'COMPLETED';
+                finalState.updatedAt = new Date().toISOString();
+            }
+            if (prState === 'CLOSED') {
+                finalState.state = 'CANCELLED';
+                finalState.updatedAt = new Date().toISOString();
+            }
+            if (finalState.state !== scheduled.state || finalState.updatedAt !== scheduled.updatedAt)
+                await this.store.saveJob(finalState);
+            if (finalState.state === 'COMPLETED' || prState !== 'OPEN')
+                await this.cleanupThreads(finalState);
+            return this.store.load(jobId);
+        }
+        finally {
+            this.reconciling = false;
+        }
+    }
+    async recoverLostExecutions(job, now) {
+        for (const task of job.tasks.filter(item => item.state === 'RUNNING')) {
+            const expired = task.leaseExpiresAt !== null && new Date(task.leaseExpiresAt).getTime() <= now;
+            const ownerLost = task.leaseOwner !== null && task.leaseOwner !== this.options.owner;
+            if (!expired && !ownerLost)
+                continue;
+            this.live.get(task.id)?.execution.cancel();
+            const planner = this.plannerLive.get(task.id);
+            if (planner) {
+                clearTimeout(planner.timer);
+                planner.controller.abort();
+                this.plannerLive.delete(task.id);
+            }
+            if (task.attempt < task.maxAttempts) {
+                transitionTask(task, 'READY');
+                task.leaseOwner = null;
+                task.leaseExpiresAt = null;
+                await this.store.saveTask(task);
+            }
+            else {
+                transitionTask(task, 'FAILED');
+                task.error = expired ? 'Lease expired after maximum attempts' : 'Execution owner restarted after maximum attempts';
+                task.leaseOwner = null;
+                task.leaseExpiresAt = null;
+                await this.store.saveTask(task);
+            }
+        }
+    }
+    async maybeCreatePlanner(job) {
+        if (job.executionMode !== 'autonomous')
+            return job;
+        const planners = job.tasks.filter(task => task.kind === 'planner').sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+        if (planners.some(task => ['QUEUED', 'READY', 'RUNNING', 'WAITING'].includes(task.state)))
+            return job;
+        if (job.tasks.some(task => task.state === 'FAILED' || task.state === 'BLOCKED'))
+            return job;
+        if (job.tasks.some(task => task.kind !== 'planner' && !['SUCCEEDED', 'CANCELLED'].includes(task.state)))
+            return job;
+        const latest = planners.at(-1);
+        if (latest?.plannerResult?.objective_status === 'satisfied')
+            return job;
+        const used = new Set(job.tasks.map(task => task.id));
+        let number = planners.length + 1;
+        let id = `planner-${number}`;
+        while (used.has(id)) {
+            number += 1;
+            id = `planner-${number}`;
+        }
+        const now = new Date().toISOString();
+        const task = { jobId: job.id, id, kind: 'planner', agentName: 'planner', parentTaskId: latest?.id ?? null, dependencies: [], capabilities: ['planner'], adapter: 'orchestrator', input: plannerInput({ job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: latest?.id ?? null }), continuation: null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: this.options.plannerTimeoutMs ?? 300000, createdAt: now, updatedAt: now };
+        await this.store.appendTask(task);
+        await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.created', 'queued', `Planner task ${task.id} created`, 'orchestrator'));
+        return this.store.load(job.id);
+    }
+    async recoverFinishedWorkers(job) {
+        for (const task of job.tasks.filter(item => item.state === 'RUNNING' && !this.live.has(item.id) && item.threadId)) {
+            const adapter = this.options.adapters.find(candidate => candidate.name === task.adapter);
+            if (!adapter?.recover)
+                continue;
+            let result = null;
+            try {
+                result = await adapter.recover(task);
+            }
+            catch {
+                result = null;
+            }
+            if (!result)
+                continue;
+            task.result = result;
+            task.error = null;
+            task.leaseOwner = null;
+            task.leaseExpiresAt = null;
+            transitionTask(task, 'SUCCEEDED');
+            await this.store.saveTask(task);
+            await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.recovered', 'succeeded', `Recovered completed task ${task.id} from durable worker thread`, 'orchestrator', { threadId: task.threadId }));
+        }
+    }
+    async launch(job, task) {
+        const adapter = this.options.adapters.find(x => x.name === task.adapter);
+        if (!adapter) {
+            transitionTask(task, 'FAILED');
+            task.error = `No adapter ${task.adapter}`;
+            await this.store.saveTask(task);
+            return;
+        }
+        const leaseMs = Math.max(this.options.leaseMs ?? 300000, task.timeoutMs);
+        const startedAt = (this.options.now ?? new Date()).getTime();
+        transitionTask(task, 'RUNNING');
+        task.attempt += 1;
+        task.leaseOwner = this.options.owner;
+        task.leaseExpiresAt = new Date(startedAt + leaseMs).toISOString();
+        task.executionId = randomUUID();
+        await this.store.saveTask(task);
+        await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.started', 'running', `Task ${task.id} started`, 'user', { adapter: adapter.id, model: task.routing?.model }));
+        const controller = new AbortController();
+        let execution;
+        const workerTask = { ...task, input: managedWorkerInput(job, task) };
+        try {
+            execution = adapter.launch(workerTask, controller.signal);
+        }
+        catch (error) {
+            await this.finish(job.id, task.id, task.executionId, null, error instanceof Error ? error.message : String(error));
+            return;
+        }
+        // A worker may reject before durable execution metadata finishes saving. Attach a guard immediately so Node never treats that race as an unhandled rejection; the durable completion handler below still records the outcome.
+        void execution.promise.catch(() => undefined);
+        task.executionId = execution.id;
+        await this.store.saveTask(task);
+        let threadPersistence = Promise.resolve();
+        const persistThread = (threadId) => {
+            threadPersistence = threadPersistence.then(() => this.persistThread(job.id, task.id, execution.id, threadId));
+        };
+        execution.onThreadStarted = persistThread;
+        if (execution.threadId)
+            persistThread(execution.threadId);
+        const timer = setTimeout(() => { controller.abort(); execution.cancel(); }, task.timeoutMs);
+        this.live.set(task.id, { taskId: task.id, execution, controller, timer });
+        this.detach(execution.promise.then(async (result) => { await threadPersistence; await this.finish(job.id, task.id, execution.id, result, null); }, async (error) => { await threadPersistence; await this.finish(job.id, task.id, execution.id, null, error instanceof Error ? error.message : String(error)); }), job.id, task.id, 'worker completion');
+    }
+    async launchPlanner(job, task) {
+        const planner = this.options.planner;
+        if (!planner) {
+            task.attempt = task.maxAttempts;
+            task.error = 'No objective planner configured';
+            transitionTask(task, 'FAILED');
+            await this.store.saveTask(task);
+            await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.failed', 'failed', `Planner ${task.id}: ${task.error}`, 'user'));
+            return;
+        }
+        const startedAt = (this.options.now ?? new Date()).getTime();
+        transitionTask(task, 'RUNNING');
+        task.attempt += 1;
+        task.leaseOwner = this.options.owner;
+        task.leaseExpiresAt = new Date(startedAt + Math.max(this.options.leaseMs ?? 300000, task.timeoutMs)).toISOString();
+        task.executionId = randomUUID();
+        await this.store.saveTask(task);
+        await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.started', 'running', `Planner task ${task.id} started`, 'orchestrator'));
+        const controller = new AbortController();
+        const executionId = task.executionId;
+        const timer = setTimeout(() => controller.abort(), task.timeoutMs);
+        this.plannerLive.set(task.id, { executionId: executionId, controller, timer });
+        let promise;
+        try {
+            promise = planner.plan({ job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: task.parentTaskId }, controller.signal);
+        }
+        catch (error) {
+            await this.finishPlanner(job.id, task.id, executionId, error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+        this.detach(promise.then(result => this.finishPlanner(job.id, task.id, executionId, null, result), error => this.finishPlanner(job.id, task.id, executionId, error instanceof Error ? error : new Error(String(error)))), job.id, task.id, 'planner completion');
+    }
+    async finishPlanner(jobId, taskId, executionId, error, raw) {
+        const live = this.plannerLive.get(taskId);
+        if (live?.executionId === executionId) {
+            clearTimeout(live.timer);
+            this.plannerLive.delete(taskId);
+        }
+        const job = await this.store.load(jobId);
+        const task = job.tasks.find(item => item.id === taskId);
+        if (!task || (executionId !== null && task.executionId !== executionId))
+            return;
+        if (task.state === 'CANCELLED')
+            return;
+        if (error) {
+            task.error = error.message;
+            task.leaseOwner = null;
+            task.leaseExpiresAt = null;
+            transitionTask(task, task.attempt < task.maxAttempts ? 'READY' : 'FAILED');
+            await this.store.saveTask(task);
+            await this.emit(eventFor(job.id, task.id, task.parentTaskId, task.state === 'FAILED' ? 'planner.failed' : 'planner.retry', task.state === 'FAILED' ? 'failed' : 'queued', `Planner ${task.id}: ${error.message}`, 'user'));
+            this.detach(this.reconcile(jobId), jobId, task.id, 'planner retry reconciliation');
+            return;
+        }
+        try {
+            const result = parsePlannerResult(raw);
+            for (const spec of result.next_tasks) {
+                const child = this.plannerChild(job, task, spec);
+                const existing = job.tasks.find(item => item.id === child.id);
+                if (!existing)
+                    await this.store.appendTask(child);
+                else if (!samePlannerChildDefinition(existing, child))
+                    throw new Error(`Planner task ${child.id} already exists with a different definition`);
+            }
+            task.plannerResult = result;
+            task.result = { summary: result.assessment, data: { objective_status: result.objective_status, next_tasks: result.next_tasks } };
+            task.error = null;
+            task.leaseOwner = null;
+            task.leaseExpiresAt = null;
+            transitionTask(task, 'SUCCEEDED');
+            await this.store.saveTask(task);
+            await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.completed', 'succeeded', `Planner ${task.id} completed: ${result.objective_status}`, 'orchestrator', { objective_status: result.objective_status }));
+        }
+        catch (caught) {
+            const message = caught instanceof Error ? caught.message : String(caught);
+            task.error = message;
+            task.leaseOwner = null;
+            task.leaseExpiresAt = null;
+            transitionTask(task, task.attempt < task.maxAttempts ? 'READY' : 'FAILED');
+            await this.store.saveTask(task);
+            await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.failed', 'failed', `Planner ${task.id}: ${message}`, 'user'));
+        }
+        this.detach(this.reconcile(jobId), jobId, task.id, 'planner follow-up reconciliation');
+    }
+    plannerChild(job, planner, spec) {
+        const now = new Date().toISOString();
+        return { jobId: job.id, id: spec.id, kind: 'work', priority: spec.priority ?? job.priority, projectName: spec.projectName, agentName: spec.agentName, parentTaskId: planner.id, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], adapter: spec.adapter ?? 'shell', input: spec.input, routing: spec.routing, continuation: spec.continuation ?? null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: spec.maxAttempts ?? 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: spec.timeoutMs ?? 300000, createdAt: now, updatedAt: now };
+    }
+    async persistThread(jobId, taskId, executionId, threadId) { const job = await this.store.load(jobId); const task = job.tasks.find(item => item.id === taskId); if (task?.executionId === executionId && task.state === 'RUNNING') {
+        task.threadId = threadId;
+        task.threadDeletedAt = null;
+        task.threadCleanupError = null;
+        await this.store.saveTask(task);
+        await this.emit(eventFor(jobId, taskId, task.parentTaskId, 'thread.started', 'running', `Worker thread ${threadId} started`, 'orchestrator', { threadId }));
+    } }
+    async finish(jobId, taskId, executionId, result, error) {
+        const live = this.live.get(taskId);
+        if (live?.execution.id === executionId) {
+            clearTimeout(live.timer);
+            this.live.delete(taskId);
+        }
+        const job = await this.store.load(jobId);
+        const task = job.tasks.find(item => item.id === taskId);
+        if (!task || task.executionId !== executionId)
+            return;
+        if (task.state === 'CANCELLED') {
+            await this.store.saveTask(task);
+            return;
+        }
+        if (error === null) {
+            task.result = result;
+            task.error = null;
+            task.leaseOwner = null;
+            task.leaseExpiresAt = null;
+            transitionTask(task, 'SUCCEEDED');
+            await this.store.saveTask(task);
+            await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.completed', 'succeeded', `Task ${task.id} completed`));
+            await this.deliverContinuation(job, task);
+        }
+        else {
+            task.error = error;
+            task.leaseOwner = null;
+            task.leaseExpiresAt = null;
+            transitionTask(task, task.attempt < task.maxAttempts ? 'READY' : 'FAILED');
+            await this.store.saveTask(task);
+            await this.emit(eventFor(job.id, task.id, task.parentTaskId, task.state === 'FAILED' ? 'task.failed' : 'task.retry', task.state === 'FAILED' ? 'failed' : 'queued', `Task ${task.id}: ${error}`, task.state === 'FAILED' ? 'user' : 'orchestrator'));
+        }
+        this.detach(this.reconcile(jobId), jobId, task.id, 'worker follow-up reconciliation');
+    }
+    async cleanupThreads(job) {
+        const adapter = this.options.adapters.find(candidate => candidate.name === 'chatgpt' && candidate.deleteThread);
+        if (!adapter?.deleteThread)
+            return;
+        for (const task of job.tasks.filter(item => item.adapter === 'chatgpt' && item.threadId && !item.threadDeletedAt)) {
+            try {
+                await adapter.deleteThread(task.threadId);
+                task.threadDeletedAt = new Date().toISOString();
+                task.threadCleanupError = null;
+                await this.store.saveTask(task);
+                await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'thread.deleted', 'succeeded', `Worker thread ${task.threadId} deleted`, 'orchestrator', { threadId: task.threadId }));
+            }
+            catch (error) {
+                task.threadCleanupError = error instanceof Error ? error.message : String(error);
+                await this.store.saveTask(task);
+                await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'thread.delete.failed', 'failed', `Worker thread cleanup failed: ${task.threadCleanupError}`, 'orchestrator', { threadId: task.threadId }));
+            }
+        }
+    }
+    async deliverContinuation(job, task) {
+        const continuation = task.continuation ?? job.continuation;
+        if (!continuation || task.continuationDeliveredAt || this.continuationLive.has(task.id))
+            return;
+        const adapter = this.options.continuations?.find(candidate => candidate.kind === continuation.kind);
+        if (!adapter) {
+            task.error = `No continuation adapter for ${continuation.kind}`;
+            await this.store.saveTask(task);
+            return;
+        }
+        this.continuationLive.add(task.id);
+        try {
+            await adapter.continue(task.result?.summary ?? '', continuation);
+            const fresh = await this.store.load(job.id);
+            const durable = fresh.tasks.find(item => item.id === task.id);
+            if (durable?.state === 'SUCCEEDED' && !durable.continuationDeliveredAt) {
+                durable.continuationDeliveredAt = new Date().toISOString();
+                await this.store.saveTask(durable);
+            }
+        }
+        catch (error) {
+            await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'continuation.failed', 'failed', `Continuation failed: ${error instanceof Error ? error.message : String(error)}`, 'user'));
+        }
+        finally {
+            this.continuationLive.delete(task.id);
+        }
+    }
+    async emit(event) { try {
+        if (this.options.emit)
+            await this.options.emit(event);
+    }
+    catch { /* observability cannot block durable execution */ } try {
+        if (this.options.eventBus)
+            await this.options.eventBus.publish(event);
+    }
+    catch (error) {
+        await this.reportTransportFailure(error);
+    } }
+    detach(promise, jobId, taskId, context) {
+        void promise.catch(error => this.reportDetachedFailure(jobId, taskId, context, error));
+    }
+    async reportDetachedFailure(jobId, taskId, context, error) {
+        if (!this.options.emit)
+            return;
+        const message = error instanceof Error ? error.message : String(error);
+        try {
+            await this.options.emit(eventFor(jobId, taskId, null, 'runtime.persistence.failed', 'failed', `${context} failed: ${message}`, 'orchestrator'));
+        }
+        catch { /* detached failure reporting must never crash the daemon */ }
+    }
+    async reportTransportFailure(error) { if (this.options.emit) {
+        try {
+            await this.options.emit(eventFor('system', 'event-bus', null, 'event.transport.failed', 'failed', `Event transport unavailable: ${error instanceof Error ? error.message : String(error)}`, 'orchestrator'));
+        }
+        catch { /* reporting is best effort */ }
+    } }
+}
+function samePlannerChildDefinition(left, right) {
+    return JSON.stringify({ id: left.id, input: left.input, priority: left.priority, projectName: left.projectName, agentName: left.agentName, dependencies: left.dependencies, capabilities: left.capabilities, adapter: left.adapter, routing: left.routing, continuation: left.continuation ?? null, maxAttempts: left.maxAttempts, timeoutMs: left.timeoutMs }) === JSON.stringify({ id: right.id, input: right.input, priority: right.priority, projectName: right.projectName, agentName: right.agentName, dependencies: right.dependencies, capabilities: right.capabilities, adapter: right.adapter, routing: right.routing, continuation: right.continuation ?? null, maxAttempts: right.maxAttempts, timeoutMs: right.timeoutMs });
+}

package/dist/registry.js

@@ -0,0 +1,27 @@
+function hasAll(values, required) { return required.every(value => values.includes(value)); }
+function matches(agent, query) {
+    if (query.capabilities && !hasAll(agent.capabilities, query.capabilities))
+        return false;
+    if (query.runtime && agent.runtime.adapter !== query.runtime)
+        return false;
+    if (query.availability && !query.availability.includes(agent.availability))
+        return false;
+    if (query.trustDomain && !agent.routing.trustDomains?.includes(query.trustDomain))
+        return false;
+    return !query.labels || Object.entries(query.labels).every(([key, value]) => agent.routing.labels?.[key] === value);
+}
+function reliability(agent) { const { succeeded, failed, timedOut } = agent.evidence.outcomes; const total = succeeded + failed + timedOut; return total === 0 ? 0 : succeeded / total; }
+export function discoverAgents(agents, query = {}) {
+    const candidates = agents.filter(agent => matches(agent, query)).map(agent => {
+        const evaluated = query.taskKind ? agent.evidence.evaluations.some(item => item.taskKind === query.taskKind) : agent.evidence.evaluations.length > 0;
+        const reasons = [query.capabilities?.length ? `capabilities: ${query.capabilities.join(', ')}` : 'capabilities matched', evaluated ? 'observed evidence available' : 'no observed evidence yet'];
+        return { agent, reasons, evidence: agent.evidence, exploratory: !evaluated };
+    });
+    return candidates.sort((left, right) => {
+        if (query.explore && left.exploratory !== right.exploratory)
+            return left.exploratory ? -1 : 1;
+        if (left.agent.availability !== right.agent.availability)
+            return left.agent.availability === 'available' ? -1 : 1;
+        return reliability(right.agent) - reliability(left.agent);
+    });
+}

package/dist/relayd.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+import { once } from 'node:events';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ChatGptAdapter, CodexAdapter, ShellAdapter } from './adapters.js';
+import { CodexThreadContinuation, CommandContinuation, WebhookContinuation } from './continuation.js';
+import { serveDashboard } from './dashboard.js';
+import { NatsEventBus } from './events.js';
+import { RepositoryWorkerPool, aggregateManagedGitHubJobs } from './pool.js';
+import { Reconciler } from './reconciler.js';
+import { dashboardManagedJobs, GitHubStore, InMemoryStore, loadManagedGitHubPullRequestGraphql } from './store.js';
+import { githubAuthContext } from './github-auth.js';
+import { isEntrypoint, startService, SERVICE_DEFAULTS } from './cli.js';
+import { codexAndZaiUsageRegistry } from './usage.js';
+import { defaultWorkspaceRoot, discoverWorkspaceRepositories } from './workspace.js';
+export const daemonHelp = `Agents Relay daemon runs the dashboard and worker pool.
+
+Usage:
+  npx agents-relayd [options]
+
+Options:
+  --repo OWNER/REPO       Watch one repository
+  --workspace PATH        Discover repositories below PATH (default: ~/Workspace)
+  --port PORT             Dashboard port (default: 8787)
+  --concurrency N         Maximum concurrent workers (default: 4)
+  --interval MS           Recovery interval
+  --events nats            Enable event wakeups
+
+Legacy single-job mode also accepts --repo OWNER/REPO --pr NUMBER --id JOB_ID.
+
+Examples:
+  npx agents-relayd --repo OWNER/REPO
+  npx agents-relayd --workspace ~/Workspace`;
+function value(args, name, fallback = '') { const index = args.indexOf(name); return index >= 0 ? args[index + 1] ?? fallback : fallback; }
+export function normalizeDaemonArguments(argv) {
+    const repository = value(argv, '--repo') || null;
+    const workspaceRoot = value(argv, '--workspace', defaultWorkspaceRoot()) || null;
+    const prValue = value(argv, '--pr');
+    const id = value(argv, '--id');
+    if ((prValue && !id) || (!prValue && id))
+        throw new Error('--pr and --id must be supplied together for legacy single-job mode');
+    if ((prValue || id) && !repository)
+        throw new Error('--repo is required for legacy single-job mode');
+    if (repository && argv.includes('--workspace'))
+        throw new Error('--repo and --workspace are mutually exclusive');
+    const pullRequest = prValue ? Number(prValue) : null;
+    if (pullRequest !== null && (!Number.isInteger(pullRequest) || pullRequest <= 0))
+        throw new Error('--pr must be positive');
+    return { repository, workspaceRoot: repository ? null : workspaceRoot, pullRequest, jobId: id || null, serviceArguments: [...argv] };
+}
+export async function runDaemon(argv) {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        console.log(daemonHelp);
+        return;
+    }
+    const normalized = normalizeDaemonArguments(argv);
+    if (normalized.pullRequest && normalized.jobId) {
+        await startService([...argv]);
+        return;
+    }
+    const auth = await githubAuthContext(argv);
+    const client = auth.client;
+    const trusted = auth.trustedAuthors;
+    const concurrency = Number(value(argv, '--concurrency', '4'));
+    const bus = value(argv, '--events') === 'nats' ? new NatsEventBus(value(argv, '--nats-url', 'nats://127.0.0.1:4222'), value(argv, '--subject-prefix', 'agents-relay.events.job')) : undefined;
+    const makeReconciler = (store, maxConcurrent) => new Reconciler(store, { owner: `relayd-${process.pid}`, maxConcurrent, leaseMs: Number(value(argv, '--lease-ms', '300000')), adapters: [new ShellAdapter(), new CodexAdapter(value(argv, '--codex', 'codex')), new ChatGptAdapter({ endpoint: value(argv, '--macbridge-url') || undefined, tokenFile: value(argv, '--macbridge-token-file') || undefined })], continuations: [new CodexThreadContinuation(value(argv, '--codex', 'codex')), new CommandContinuation(), new WebhookContinuation()], eventBus: bus });
+    const repositories = normalized.repository
+        ? [normalized.repository]
+        : (await discoverWorkspaceRepositories(normalized.workspaceRoot ?? defaultWorkspaceRoot())).map(item => item.repository);
+    if (repositories.length === 0)
+        throw new Error(`No Git repositories with GitHub origins found under ${normalized.workspaceRoot ?? defaultWorkspaceRoot()}`);
+    const pool = new RepositoryWorkerPool(client, repositories, trusted, concurrency, makeReconciler);
+    const cacheDirectory = join(homedir(), '.agents-relay');
+    const cacheFile = join(cacheDirectory, 'dashboard-jobs.json');
+    let cachedOverviews = [];
+    try {
+        const parsed = JSON.parse(await readFile(cacheFile, 'utf8'));
+        if (Array.isArray(parsed))
+            cachedOverviews = parsed;
+    }
+    catch { /* first run or invalid cache */ }
+    const refreshAll = async () => {
+        if (client.rateLimitStatus().limited)
+            return cachedOverviews;
+        try {
+            cachedOverviews = dashboardManagedJobs(await aggregateManagedGitHubJobs(client, repositories, trusted));
+            try {
+                await mkdir(cacheDirectory, { recursive: true });
+                await writeFile(cacheFile, JSON.stringify(cachedOverviews), 'utf8');
+            }
+            catch { /* cache is best effort */ }
+            return cachedOverviews;
+        }
+        catch (error) {
+            process.stderr.write(`warning: workspace job refresh unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+            return cachedOverviews;
+        }
+    };
+    const overviews = async (forceRefresh = false) => forceRefresh ? refreshAll() : cachedOverviews;
+    const persistCache = async () => {
+        try {
+            await mkdir(cacheDirectory, { recursive: true });
+            await writeFile(cacheFile, JSON.stringify(cachedOverviews), 'utf8');
+        }
+        catch { /* cache is best effort */ }
+    };
+    const refreshPullRequest = async (repository, prNumber) => {
+        const refreshed = await loadManagedGitHubPullRequestGraphql(client, repository, prNumber, trusted);
+        cachedOverviews = cachedOverviews.filter(item => item.job.repository !== repository || item.job.prNumber !== prNumber);
+        cachedOverviews.push(...refreshed);
+        cachedOverviews = dashboardManagedJobs(cachedOverviews);
+        await persistCache();
+        return refreshed;
+    };
+    const initial = await refreshAll();
+    const fallback = initial[0]?.job;
+    const dashboardStore = fallback ? new GitHubStore(client, fallback.repository, fallback.prNumber, trusted) : new InMemoryStore();
+    const secretFile = value(argv, '--github-webhook-secret-file');
+    const secret = value(argv, '--github-webhook-secret') || process.env.AGENTS_RELAY_GITHUB_WEBHOOK_SECRET || (secretFile ? (await readFile(secretFile, 'utf8')).trim() : '');
+    const webhook = secret ? {
+        secret,
+        repositories: new Set(repositories),
+        wake: async (event) => {
+            if (!event.repository || !event.pullRequest)
+                return;
+            try {
+                const refreshed = await refreshPullRequest(event.repository, event.pullRequest);
+                for (const item of refreshed)
+                    await pool.webhookWake(bus, item.job, event.deliveryId, event.event, event.action);
+            }
+            catch (error) {
+                process.stderr.write(`warning: webhook PR refresh unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+            }
+        }
+    } : undefined;
+    const exactJob = async (jobId) => {
+        const cached = cachedOverviews.find(item => item.job.id === jobId);
+        if (!cached)
+            return null;
+        try {
+            const refreshed = (await refreshPullRequest(cached.job.repository, cached.job.prNumber)).find(item => item.job.id === jobId);
+            if (!refreshed)
+                return null;
+            return { ...refreshed.job, githubState: refreshed.githubState, mergedAt: refreshed.mergedAt, closedAt: refreshed.closedAt, draft: refreshed.draft };
+        }
+        catch (error) {
+            process.stderr.write(`warning: selected job refresh unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+            return null;
+        }
+    };
+    const usageRegistry = codexAndZaiUsageRegistry();
+    const server = serveDashboard(dashboardStore, Number(value(argv, '--port', String(SERVICE_DEFAULTS.port))), bus, Number(value(argv, '--refresh-ms', String(SERVICE_DEFAULTS.dashboardRefreshMs))), fallback?.id, usageRegistry, overviews, webhook, () => client.rateLimitStatus(), exactJob);
+    await once(server, 'listening');
+    const reconcileSafely = async () => {
+        if (client.rateLimitStatus().limited)
+            return;
+        try {
+            await pool.reconcile();
+        }
+        catch (error) {
+            process.stderr.write(`warning: workspace reconcile unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    };
+    const watchdogDefault = webhook ? SERVICE_DEFAULTS.webhookWatchdogMs : SERVICE_DEFAULTS.watchdogMs;
+    const interval = setInterval(() => void reconcileSafely(), Number(value(argv, '--interval', String(watchdogDefault))));
+    interval.unref();
+    const stopWatch = bus ? await pool.watch(bus) : async () => { };
+    const stop = () => { clearInterval(interval); void stopWatch().finally(() => server.close(() => process.exit(0))); };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    console.log('Dashboard listening; repository worker pool active');
+    if (!client.rateLimitStatus().limited)
+        void pool.reconcileKnown(initial).catch(error => process.stderr.write(`warning: startup reconciliation unavailable: ${error instanceof Error ? error.message : String(error)}\n`));
+}
+if (isEntrypoint(import.meta.url))
+    runDaemon(process.argv.slice(2)).catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });