agents-relay 1.0.0

package/dist/usage.js

@@ -0,0 +1,370 @@
+import { createReadStream } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { spawn } from 'node:child_process';
+function finiteNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+function finitePercent(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 100 ? value : null;
+}
+function positiveMinutes(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null;
+}
+function epochSeconds(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null;
+}
+function parseWindow(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const raw = value;
+    const usedPercent = finitePercent(raw.used_percent);
+    const windowMinutes = positiveMinutes(raw.window_minutes);
+    if (usedPercent === null || windowMinutes === null)
+        return null;
+    return { usedPercent, windowMinutes, resetsAt: epochSeconds(raw.resets_at) };
+}
+function rateLimitsFromLine(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        const event = parsed;
+        if (event.type !== 'event_msg')
+            return null;
+        const payload = event.payload;
+        if (!payload || typeof payload !== 'object')
+            return null;
+        const message = payload;
+        if (message.type !== 'token_count')
+            return null;
+        const rateLimits = message.rate_limits;
+        if (!rateLimits || typeof rateLimits !== 'object')
+            return null;
+        const limits = rateLimits;
+        const windows = [parseWindow(limits.primary), parseWindow(limits.secondary)].filter((window) => window !== null);
+        const timestamp = typeof event.timestamp === 'string' && !Number.isNaN(Date.parse(event.timestamp))
+            ? event.timestamp
+            : new Date(0).toISOString();
+        return { timestamp, windows };
+    }
+    catch {
+        return null;
+    }
+}
+export class CodexApiUsageReader {
+    now;
+    constructor(now = () => new Date()) {
+        this.now = now;
+    }
+    async read() {
+        const generatedAt = this.now().toISOString();
+        return await new Promise(resolve => {
+            const child = spawn('codex', ['app-server', '--stdio'], { stdio: ['pipe', 'pipe', 'ignore'] });
+            const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+            const finish = (snapshot) => { lines.close(); child.kill(); resolve(snapshot); };
+            const timer = setTimeout(() => finish({ available: false, generatedAt, fiveHour: null, weekly: null, reason: 'Codex app-server rate-limit request timed out.' }), 10_000);
+            lines.on('line', line => {
+                try {
+                    const message = JSON.parse(line);
+                    if (message.id !== 2)
+                        return;
+                    clearTimeout(timer);
+                    const parse = (window) => {
+                        if (!window)
+                            return null;
+                        const usedPercent = finitePercent(window.usedPercent);
+                        const windowMinutes = positiveMinutes(window.windowDurationMins);
+                        return usedPercent === null || windowMinutes === null ? null : { usedPercent, windowMinutes, resetsAt: epochSeconds(window.resetsAt) };
+                    };
+                    const limits = message.result?.rateLimits;
+                    const primary = parse(limits?.primary);
+                    const secondary = parse(limits?.secondary);
+                    const windows = [primary, secondary].filter((window) => window !== null);
+                    const fiveHour = windows.find(window => window.windowMinutes === 300) ?? null;
+                    const weekly = windows.find(window => window.windowMinutes === 10_080) ?? null;
+                    const available = fiveHour !== null && weekly !== null;
+                    finish({ available, generatedAt, fiveHour, weekly, reason: available ? null : 'Codex app-server did not return both account quota windows.' });
+                }
+                catch {
+                    return;
+                }
+            });
+            child.once('error', () => { clearTimeout(timer); finish({ available: false, generatedAt, fiveHour: null, weekly: null, reason: 'Codex app-server could not be started.' }); });
+            child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { clientInfo: { name: 'agents-relay', version: '1' }, capabilities: {} } }) + '\n');
+            setTimeout(() => child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'account/rateLimits/read', params: {} }) + '\n'), 100);
+        });
+    }
+}
+export class CodexSessionUsageReader {
+    codexHome;
+    lookbackDays;
+    cacheTtlMs;
+    now;
+    cache = null;
+    constructor(codexHome = join(homedir(), '.codex'), lookbackDays = 8, cacheTtlMs = 10_000, now = () => new Date()) {
+        this.codexHome = codexHome;
+        this.lookbackDays = lookbackDays;
+        this.cacheTtlMs = cacheTtlMs;
+        this.now = now;
+    }
+    async usageFiles(cutoff) {
+        const files = [];
+        for (const root of [join(this.codexHome, 'sessions'), join(this.codexHome, 'archived_sessions')]) {
+            await this.collectFiles(root, cutoff, files, 0);
+        }
+        return files.sort((left, right) => right.modifiedAt.getTime() - left.modifiedAt.getTime());
+    }
+    async collectFiles(directory, cutoff, files, depth) {
+        if (depth > 5)
+            return;
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const path = join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await this.collectFiles(path, cutoff, files, depth + 1);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.jsonl'))
+                continue;
+            try {
+                const metadata = await stat(path);
+                if (metadata.mtime >= cutoff)
+                    files.push({ path, modifiedAt: metadata.mtime });
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    async read() {
+        const now = this.now();
+        if (this.cache && now.getTime() - this.cache.cachedAt < this.cacheTtlMs)
+            return this.cache.snapshot;
+        const cutoff = new Date(now.getTime() - this.lookbackDays * 86_400_000);
+        const files = await this.usageFiles(cutoff);
+        let latestTimestamp = '';
+        let latestWindows = [];
+        for (const file of files) {
+            const stream = createReadStream(file.path, { encoding: 'utf8' });
+            const lines = createInterface({ input: stream, crlfDelay: Infinity });
+            try {
+                for await (const line of lines) {
+                    if (!line.includes('"rate_limits"'))
+                        continue;
+                    const telemetry = rateLimitsFromLine(line);
+                    if (telemetry && telemetry.timestamp > latestTimestamp) {
+                        latestTimestamp = telemetry.timestamp;
+                        latestWindows = telemetry.windows;
+                    }
+                }
+            }
+            finally {
+                lines.close();
+                stream.destroy();
+            }
+        }
+        const fiveHour = latestWindows.find(window => window.windowMinutes === 300) ?? null;
+        const weekly = latestWindows.find(window => window.windowMinutes === 10_080) ?? null;
+        const telemetryAgeMs = latestTimestamp ? now.getTime() - Date.parse(latestTimestamp) : Number.POSITIVE_INFINITY;
+        const fresh = telemetryAgeMs >= 0 && telemetryAgeMs <= 15 * 60_000;
+        const available = fresh && fiveHour !== null && weekly !== null;
+        const snapshot = {
+            available,
+            generatedAt: now.toISOString(),
+            fiveHour,
+            weekly,
+            reason: available
+                ? null
+                : latestTimestamp && !fresh
+                    ? 'Latest Codex account rate-limit telemetry is stale.'
+                    : files.length
+                        ? 'Latest Codex account telemetry does not expose current 5-hour and weekly rate-limit windows.'
+                        : 'No recent Codex account rate-limit telemetry is available.',
+        };
+        this.cache = { cachedAt: now.getTime(), snapshot };
+        return snapshot;
+    }
+}
+export class ZaiUsageReader {
+    apiKey;
+    endpoint;
+    fetchImpl;
+    now;
+    constructor(apiKey = process.env.ZAI_API_KEY ?? '', endpoint = 'https://api.z.ai/api/monitor/usage/quota/limit', fetchImpl = fetch, now = () => new Date()) {
+        this.apiKey = apiKey;
+        this.endpoint = endpoint;
+        this.fetchImpl = fetchImpl;
+        this.now = now;
+    }
+    async read() {
+        const generatedAt = this.now().toISOString();
+        if (!this.apiKey) {
+            return { available: false, generatedAt, fiveHour: null, weekly: null, reason: 'ZAI_API_KEY is not configured.' };
+        }
+        try {
+            const response = await this.fetchImpl(this.endpoint, {
+                headers: { Authorization: `Bearer ${this.apiKey}`, Accept: 'application/json' },
+            });
+            if (!response.ok) {
+                return { available: false, generatedAt, fiveHour: null, weekly: null, reason: `Z.ai usage request failed with HTTP ${response.status}.` };
+            }
+            const payload = await response.json();
+            const limits = Array.isArray(payload?.data?.limits) ? payload.data.limits : [];
+            const readLimit = (unit, windowMinutes) => {
+                const raw = limits.find(limit => (limit.type === 'TOKENS_LIMIT' || limit.type === 'CREDIT_LIMIT') && limit.unit === unit);
+                if (!raw)
+                    return null;
+                const usedPercent = finitePercent(raw.percentage);
+                if (usedPercent === null)
+                    return null;
+                const resetMs = typeof raw.nextResetTime === 'number' && Number.isFinite(raw.nextResetTime) ? raw.nextResetTime : null;
+                return { usedPercent, windowMinutes, resetsAt: resetMs === null ? null : Math.floor(resetMs / 1000) };
+            };
+            const fiveHour = readLimit(3, 300);
+            const weekly = readLimit(6, 10_080);
+            const available = fiveHour !== null && weekly !== null;
+            return {
+                available,
+                generatedAt,
+                fiveHour,
+                weekly,
+                reason: available ? null : 'Z.ai returned no usable 5-hour and weekly Coding Plan quota windows.',
+            };
+        }
+        catch {
+            return { available: false, generatedAt, fiveHour: null, weekly: null, reason: 'Z.ai account usage request could not be completed.' };
+        }
+    }
+}
+export class DeepSeekCreditReader {
+    apiKey;
+    endpoint;
+    fetchImpl;
+    now;
+    constructor(apiKey = process.env.DEEPSEEK_API_KEY ?? '', endpoint = 'https://api.deepseek.com/user/balance', fetchImpl = fetch, now = () => new Date()) {
+        this.apiKey = apiKey;
+        this.endpoint = endpoint;
+        this.fetchImpl = fetchImpl;
+        this.now = now;
+    }
+    async read() {
+        const generatedAt = this.now().toISOString();
+        if (!this.apiKey)
+            return { available: false, generatedAt, balances: [], reason: 'DEEPSEEK_API_KEY is not configured.' };
+        try {
+            const response = await this.fetchImpl(this.endpoint, { headers: { Authorization: `Bearer ${this.apiKey}`, Accept: 'application/json' } });
+            if (!response.ok)
+                return { available: false, generatedAt, balances: [], reason: `DeepSeek balance request failed with HTTP ${response.status}.` };
+            const payload = await response.json();
+            const balances = (Array.isArray(payload.balance_infos) ? payload.balance_infos : []).map(info => ({
+                currency: typeof info.currency === 'string' ? info.currency : 'credit',
+                total: finiteNumber(info.total_balance),
+                used: null,
+                remaining: finiteNumber(info.total_balance),
+            })).filter(balance => balance.remaining !== null);
+            return { available: payload.is_available === true && balances.length > 0, generatedAt, balances, reason: balances.length ? null : 'DeepSeek returned no usable balance information.' };
+        }
+        catch {
+            return { available: false, generatedAt, balances: [], reason: 'DeepSeek balance request could not be completed.' };
+        }
+    }
+}
+export class OpenRouterCreditReader {
+    apiKey;
+    endpoint;
+    fetchImpl;
+    now;
+    constructor(apiKey = process.env.OPENROUTER_API_KEY ?? '', endpoint = 'https://openrouter.ai/api/v1/credits', fetchImpl = fetch, now = () => new Date()) {
+        this.apiKey = apiKey;
+        this.endpoint = endpoint;
+        this.fetchImpl = fetchImpl;
+        this.now = now;
+    }
+    async read() {
+        const generatedAt = this.now().toISOString();
+        if (!this.apiKey)
+            return { available: false, generatedAt, balances: [], reason: 'OPENROUTER_API_KEY is not configured.' };
+        try {
+            const response = await this.fetchImpl(this.endpoint, { headers: { Authorization: `Bearer ${this.apiKey}`, Accept: 'application/json' } });
+            if (!response.ok)
+                return { available: false, generatedAt, balances: [], reason: `OpenRouter credits request failed with HTTP ${response.status}; this endpoint requires a management key.` };
+            const payload = await response.json();
+            const total = finiteNumber(payload.data?.total_credits);
+            const used = finiteNumber(payload.data?.total_usage);
+            const remaining = total !== null && used !== null ? total - used : null;
+            const balances = total === null && used === null ? [] : [{ currency: 'USD', total, used, remaining }];
+            return { available: balances.length > 0, generatedAt, balances, reason: balances.length ? null : 'OpenRouter returned no usable credit information.' };
+        }
+        catch {
+            return { available: false, generatedAt, balances: [], reason: 'OpenRouter credits request could not be completed.' };
+        }
+    }
+}
+export class UsageRegistry {
+    openaiReader;
+    zaiReader;
+    deepSeekReader;
+    openRouterReader;
+    constructor(openaiReader, zaiReader = new ZaiUsageReader(), deepSeekReader = null, openRouterReader = null) {
+        this.openaiReader = openaiReader;
+        this.zaiReader = zaiReader;
+        this.deepSeekReader = deepSeekReader;
+        this.openRouterReader = openRouterReader;
+    }
+    async snapshot() {
+        const [openai, zai, deepseek, openrouter] = await Promise.all([
+            this.openaiReader.read(),
+            this.zaiReader.read(),
+            this.deepSeekReader?.read() ?? Promise.resolve(null),
+            this.openRouterReader?.read() ?? Promise.resolve(null),
+        ]);
+        const credits = [];
+        if (deepseek)
+            credits.push({ id: 'deepseek', label: 'DeepSeek', credits: deepseek });
+        if (openrouter)
+            credits.push({ id: 'openrouter', label: 'OpenRouter', credits: openrouter });
+        return {
+            generatedAt: new Date().toISOString(),
+            providers: [
+                { id: 'openai', label: 'OpenAI', usage: openai },
+                { id: 'zai', label: 'Z.ai', usage: zai },
+            ],
+            credits,
+        };
+    }
+}
+export class UnavailableUsageReader {
+    reason;
+    now;
+    constructor(reason, now = () => new Date()) {
+        this.reason = reason;
+        this.now = now;
+    }
+    async read() {
+        return {
+            available: false,
+            generatedAt: this.now().toISOString(),
+            fiveHour: null,
+            weekly: null,
+            reason: this.reason,
+        };
+    }
+}
+export function codexAndZaiUsageRegistry(codexHome, _legacyWindowDays) {
+    return new UsageRegistry(new CodexApiUsageReader(), new ZaiUsageReader(), process.env.DEEPSEEK_API_KEY ? new DeepSeekCreditReader() : null, process.env.OPENROUTER_API_KEY ? new OpenRouterCreditReader() : null);
+}

package/dist/workspace.js

@@ -0,0 +1,76 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export function defaultWorkspaceRoot() {
+    return join(homedir(), 'Workspace');
+}
+export function githubRepositoryFromRemote(remote) {
+    const value = remote.trim().replace(/\.git$/, '');
+    const match = value.match(/github\.com[/:]([^/]+)\/([^/]+)$/i);
+    return match ? `${match[1]}/${match[2]}` : null;
+}
+async function hasGitDirectory(path) {
+    try {
+        await stat(join(path, '.git'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function discoverGitRepositories(root) {
+    const found = [];
+    const visit = async (directory) => {
+        if (await hasGitDirectory(directory)) {
+            found.push(directory);
+            return;
+        }
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        await Promise.all(entries.filter(entry => entry.isDirectory() && !['node_modules', '.git', '.worktrees', '.backup'].includes(entry.name)).map(entry => visit(join(directory, entry.name))));
+    };
+    await visit(resolve(root));
+    return found.sort((a, b) => relative(root, a).localeCompare(relative(root, b)));
+}
+async function origin(path) {
+    try {
+        return (await execFileAsync('git', ['-C', path, 'remote', 'get-url', 'origin'])).stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function discoverWorkspaceRepositories(root) {
+    const paths = await discoverGitRepositories(root);
+    const discovered = await Promise.all(paths.map(async (path) => {
+        const repository = githubRepositoryFromRemote(await origin(path) ?? '');
+        return repository ? { path, repository } : null;
+    }));
+    const unique = new Map();
+    for (const item of discovered) {
+        if (!item)
+            continue;
+        const current = unique.get(item.repository);
+        if (!current || repositoryPathRank(item.path, root) < repositoryPathRank(current.path, root))
+            unique.set(item.repository, item);
+    }
+    return [...unique.values()].sort((a, b) => a.repository.localeCompare(b.repository));
+}
+function repositoryPathRank(path, root) {
+    const relativePath = relative(root, path);
+    if (!relativePath.includes('/'))
+        return 0;
+    if (relativePath.startsWith('.worktrees/'))
+        return 2;
+    if (relativePath.startsWith('.backup/'))
+        return 3;
+    return 1;
+}

package/docs/agent-network.md

@@ -0,0 +1,34 @@
+# Agent Network enhancement
+
+## Objective
+
+Evolve Agents Relay from task adapters into a minimal network of independently registered, result-owning agents while retaining GitHub PR state as durable truth and preserving shell/Codex/ChatGPT worker support.
+
+## Scope shipped
+
+- Typed agent registration distinguishes identity, role/responsibility, boundaries, claimed capabilities, endpoint/runtime, availability, and routing metadata.
+- Trusted `agents-relay:agent:v1` markers persist registrations in the existing GitHub PR comment store; no second database is introduced.
+- `agent-register` and `agent-discover` are machine-driven CLI/core surfaces.
+- Discovery applies hard requirements first, then returns explainable evidence and a small policy ranking with optional exploration of unobserved agents.
+- Evidence models representative evaluations, historical outcomes, reliability inputs, latency, and cost without fabricating a universal score.
+- Documentation defines the single-orchestrator UX, durable task/lease/retry/reconciliation model, and a narrow future authenticated remote job/status contract.
+
+## Non-goals
+
+This PR does not build a public marketplace, broad multi-owner control plane, unauthenticated HTTP endpoint, private-data/credential routing, isolation/billing/trust enforcement, or automatic final agent selection. Adapters remain execution runtimes; events remain live observability and never durable truth.
+
+## Acceptance criteria
+
+- Existing task, scheduler, lease/recovery, continuation, dashboard, and ChatGPT adapter behavior remains green.
+- Agents can be registered and discovered from the same durable PR-backed store.
+- Discovery rejects unmet capabilities/runtime/trust/availability requirements and exposes evidence rather than an opaque score.
+- Registration and discovery work without a human web form.
+- The future remote surface is explicitly limited to authenticated create/submit and status operations, with intention-only/public jobs separated from private-data jobs.
+
+## Validation
+
+Run `npm test`, `npm run build`, and `git diff --check`. The implementation adds registry/discovery tests and store round-trip/forgery tests while retaining the existing test suite.
+
+## Future direction
+
+Add authenticated remote submission only when the host has a concrete identity and trust boundary. Then add durable remote task leases/heartbeats and recovery integration, richer evidence aggregation, policy-pluggable matching, and security/isolation gates for private jobs. Keep GitHub PR markers authoritative throughout.

package/docs/architecture.md

@@ -0,0 +1,120 @@
+# Agents Relay v1 architecture
+
+## Goal
+
+Provide a generic, shareable async agent job system where agents can submit durable child tasks, specialized workers execute them asynchronously, results are persisted, and the parent agent can continue when dependencies become ready.
+
+## Core model
+
+- **GitHub pull request** — durable top-level job container and audit surface.
+- **Job marker comment** — durable job metadata and continuation state.
+- **Task marker comments** — append-friendly durable child-task records.
+- **Agents Relay daemon** — reconciler, scheduler, dispatcher, lease/recovery manager, continuation engine, and dashboard server.
+- **Agent adapters** — pluggable execution backends such as Codex and shell commands.
+- **Event adapter** — optional low-latency notification/wake channel; events never replace durable PR state.
+- **Periodic watchdog** — low-frequency recovery sweep that re-reads durable PR/job state to repair missed wakeups and recover stale execution state (30 minutes with webhook mode by default; 5 minutes without webhooks for compatibility).
+- **Artifact references** — large/private outputs stay outside GitHub comments; task records store references.
+
+## Agent network slice
+
+An agent is a registered, result-owning worker/social role with a responsibility boundary. It is not the same thing as a skill (a callable capability) or an execution adapter (shell, Codex, or ChatGPT). Registration is machine-driven through the CLI/core API and is stored as a trusted `agents-relay:agent:v1` marker comment on the same PR.
+
+Registration records identity/name, role and responsibility, claimed capabilities, explicit boundaries/non-goals, endpoint/runtime, availability, and routing metadata. `agent-register` and `agent-discover` provide the smallest useful registry surface. Discovery applies hard filters first and returns observed evidence and reasons rather than a universal score. Evidence can include representative evaluations, outcomes, reliability, latency, and cost. `--explore` allows new/unobserved agents to be considered first; the orchestrator still owns the final choice.
+
+The registry does not yet execute remote agents or expose a public marketplace. A constrained ChatGPT/voice/mobile runtime should eventually use a small authenticated service surface with only `POST /jobs` (intention-only/public jobs) and `GET /jobs/:id`; credentials and private payloads must stay out of PR markers and events. Private-data/credential jobs, multi-owner trust, isolation, billing, and public discovery are future security-gated work.
+
+## Execution modes
+
+Jobs persist `executionMode` as `fixed` or `autonomous`; missing mode in legacy
+markers is read as `fixed`. Fixed is the default and keeps the v1 submit flow
+unchanged. Autonomous jobs use the existing task records and parent hierarchy:
+when all currently runnable work is settled and no planner task is active,
+reconciliation appends one durable `kind: "planner"` task. The planner returns
+typed `objective_status`, `assessment`, and `next_tasks` values. Each
+`next_tasks` item becomes a normal child task of that planner task.
+
+Stable task IDs and append-if-same-definition behavior make planner retries
+idempotent. Leases, owner recovery, and completion decisions remain in the
+reconciler; planner output never directly marks a job complete.
+
+## Reconciliation rule
+
+Every wake-up means only: "the durable state may have changed." The daemon reloads the PR and task records, derives desired actions, and reconciles actual execution state. It never advances a job solely because an event claimed something happened. Event-driven and periodic reconciles are single-flight within one process; a periodic sweep may create the next autonomous planner task only from durable settled state.
+
+## State
+
+Job states:
+
+OPEN -> RUNNING -> WAITING|BLOCKED -> COMPLETED|FAILED|CANCELLED
+
+Task states:
+
+QUEUED -> READY -> RUNNING -> WAITING|BLOCKED -> SUCCEEDED|FAILED|CANCELLED
+
+A task becomes READY when all declared dependencies have succeeded and any approval gate is satisfied. Autonomous completion additionally requires a durable planner result of `satisfied`, every planner/work task to be `SUCCEEDED`, and no unresolved failure or blocked task.
+
+## Task record
+
+Each task is one GitHub PR comment containing a human-readable summary plus a hidden `agents-relay:task:v1` JSON marker. Minimum durable fields:
+
+- task id and parent task id
+- dependencies
+- capabilities
+- adapter + execution input
+- routing decision for model-backed workers
+- state + attempt
+- lease owner and expiry
+- execution id/thread id
+- result summary and artifact references
+- timestamps
+
+Task submission is append-only at creation time, which avoids a single giant mutable manifest and makes agent-to-agent delegation natural.
+
+## Execution
+
+1. An agent submits a task to the PR.
+2. A task comment is created durably.
+3. The relay wakes and reloads the PR.
+4. Scheduler marks dependency-satisfied tasks ready.
+5. Dispatcher validates routing/capabilities and claims a lease.
+6. Adapter launches the worker.
+7. Worker reports progress over the optional event channel.
+8. Relay persists terminal task state/result back into the task comment.
+9. Relay reconciles dependents and/or resumes the parent continuation.
+10. Periodic watchdog reconciliation only repairs missed wake-ups and expired leases; webhook mode uses targeted reconciliation for the normal path and cached dashboard reads do not trigger broad discovery.
+
+## Continuations
+
+Continuations are adapters, separate from worker adapters. v1 supports Codex-thread continuation plus a generic command/webhook contract. Hosted web chat continuations may rely on their host integration; their durable state remains recoverable from the PR.
+
+## v1 acceptance criteria
+
+1. A reusable TypeScript package/CLI named `agents-relay`.
+2. GitHub PR/comment durable store with job/task marker parsing and updates.
+3. CLI to initialize a PR job, submit child tasks, inspect status, reconcile, retry/cancel tasks, and run the daemon.
+4. Dependency scheduling and nested parent/child lineage.
+5. Worker lease, expiry detection, recovery, retry, timeout, and cancellation semantics.
+6. At least Codex and shell worker adapters behind one adapter interface.
+7. Routing metadata is mandatory before a model-backed worker can launch.
+8. Optional event integration for wake-ups/progress with durable-state reconciliation.
+9. Parent continuation interface with Codex-thread continuation implemented.
+10. Dashboard web page showing jobs, task tree/state, worker/model, dependencies, results, leases, and live events/status.
+11. SSE or equivalent local live dashboard updates.
+12. Tests for marker parsing, state transitions, scheduling, reconciliation/recovery, and API/dashboard data.
+13. `skills/agents-relay/SKILL.md` plus supporting agent files describing how an agent submits async work, propagates lineage, consumes results, and treats events vs durable state.
+14. Documentation and a runnable local dogfood example.
+15. Browser-level verification of the dashboard before merge.
+
+## Non-goals for v1
+
+- Reimplement GitHub as a database.
+- Build a general workflow-language/DAG editor.
+- Require Redis, Postgres, Temporal, or Kubernetes.
+- Make NATS mandatory.
+- Implement a hosted multi-tenant control plane.
+- Encode domain-specific agent roles in the core runtime.
+- Build a broad public agent marketplace or unauthenticated remote HTTP API.
+
+## Dogfood
+
+This PR is the first top-level Agents Relay job. Development, review, fixes, and verification remain on this PR until the v1 acceptance criteria are met.