agents-relay 1.0.42 → 1.0.43

package/README.md

@@ -48,6 +48,13 @@ retries and daemon restarts do not create duplicate work.
 Task producers must follow `skills/agents-relay/contracts/task-job-contract.md`; that shared skill contract defines story size, lifecycle events, review, and auto-merge semantics.
 All task producers use the same story-size contract: `S`≈5 minutes, `M`≈15 minutes, and `L`≈45 minutes of normal-reasoning execution, with `M` as the default. `high` reasoning doubles that overall window. ChatGPT Browser Worker start-ack timeout is derived as one third of the effective overall timeout, clamped between 1 and 5 minutes. Orchestrators and planners should choose `storySize`, not raw timeout milliseconds; `--timeout` remains only as an explicit compatibility/debug override.
 
+Autonomous jobs can also be scheduled without a Relay database. The job marker
+stores a five-field cron expression, IANA timezone, next run, and missed-run /
+concurrency policy; GitHub issue labels provide the indexed discovery surface.
+A repository heartbeat invokes `tick` at 10-minute resolution. See
+[Scheduled autonomous jobs](docs/scheduled-autonomous-jobs.md) for the exact
+operational contract.
+
 job create first resolves an existing open PR with the same head/base, then creates it only when needed. Re-running it is idempotent: it reuses the PR and maintains exactly one trusted agents-relay:job:v1 marker.
 Use `--start` to create/reuse the job and submit its initial task in one invocation. Start mode requires explicit `--adapter`, `--model`, `--output`, and non-empty `--input`; the task ID defaults to `initial`. Re-running with the same task definition reuses that task and never duplicates it. Omitting `--start` preserves create-only behavior, leaving an `OPEN` job with zero tasks until a caller submits work.
 

package/dist/cli.js

@@ -15,10 +15,11 @@ import { serveDashboard } from './dashboard.js';
 import { codexAndZaiUsageRegistry } from './usage.js';
 import { discoverAgents } from './registry.js';
 import { AgentObjectivePlanner, CommandObjectivePlanner, orchestratorPlanningDecision } from './planner.js';
-import { extendRetryBudget } from './scheduler.js';
+import { extendRetryBudget, parseJobSchedule } from './scheduler.js';
+import { dueBuckets, processDueScheduledJobs, syncScheduleLabels } from './scheduled-jobs.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { defaultWorkspaceRoot, resolveManagedProjectPath } from './workspace.js';
-const usage = 'agents-relay <job|task|context|init|submit|record|agent-register|agent-discover|status|reconcile|retry|cancel|serve> [options]';
+const usage = 'agents-relay <job|task|context|init|submit|record|agent-register|agent-discover|status|reconcile|tick|retry|cancel|serve> [options]';
 const help = {
     root: `Agents Relay coordinates durable asynchronous agent jobs through GitHub pull requests.
 
@@ -36,6 +37,7 @@ Commands:
   agent-discover           Find registered agents matching hard filters
   status                   Show the durable job state
   reconcile                Run reconciliation once
+  tick                     Run the indexed autonomous scheduler heartbeat
   retry|cancel             Change a task state
   serve                    Run the dashboard and reconciliation service
 
@@ -58,6 +60,11 @@ Common options:
   --title TEXT             Job title
   --objective TEXT         Objective for autonomous mode
   --mode fixed|autonomous  Execution mode (default: fixed)
+  --schedule CRON          Autonomous schedule; minute resolution is 10 minutes
+  --schedule-timezone TZ   IANA timezone for --schedule (default: UTC)
+  --schedule-next-run ISO  Optional first run (must match the cron expression)
+  --missed-run-policy run|skip   Run each missed slot or skip to the next future slot
+  --schedule-concurrency skip|queue  Skip or retain the slot while work is active
   --start                   Create/reuse the job and submit its initial task
 
 Example:
@@ -140,6 +147,13 @@ Required: --file PATH for local demo mode, or --repo OWNER/REPO --pr NUMBER --id
 
 Example:
   npx agents-relay reconcile --repo OWNER/REPO --pr 12 --id job-1`,
+    tick: `Process autonomous jobs indexed into current/recent GitHub next-run buckets.
+
+Required: --repo OWNER/REPO.
+Common: --lookback-buckets N (default 3).
+
+Example:
+  npx agents-relay tick --repo OWNER/REPO`,
     init: `Initialize a new job. GitHub mode requires --repo and --pr; local mode requires explicit --file.
 
 Common: --id ID, --title TEXT, --objective TEXT, --mode fixed|autonomous, --priority P0|P1|P2|P3.
@@ -257,6 +271,19 @@ export function chatGptTabClosePolicy(args) {
 }
 function requestedExecutionMode(args) { const value = arg(args, '--mode', arg(args, '--execution-mode')); return value ? executionMode(args) : undefined; }
 function continuation(args) { const kind = arg(args, '--continue-kind'); const target = arg(args, '--continue-target'); return kind && target ? { kind: kind, target, input: arg(args, '--continue-input') || undefined } : null; }
+function scheduleFromArgs(args) {
+    const cron = arg(args, '--schedule');
+    if (!cron)
+        return undefined;
+    const nextRunAt = arg(args, '--schedule-next-run') || undefined;
+    return parseJobSchedule({
+        cron,
+        timezone: arg(args, '--schedule-timezone', 'UTC'),
+        nextRunAt,
+        missedRunPolicy: arg(args, '--missed-run-policy', 'skip'),
+        concurrencyPolicy: arg(args, '--schedule-concurrency', 'skip'),
+    });
+}
 export async function ensureManagedGitHubJob(client, repositoryName, trustedAuthors, options) {
     if (!options.id)
         throw new Error('--id is required for managed GitHub jobs');
@@ -278,6 +305,8 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
         job.objective = options.objective;
     if (options.executionMode)
         job.executionMode = options.executionMode;
+    if (options.schedule)
+        job.schedule = options.schedule;
     if (options.autoMerge !== undefined)
         job.autoMerge = options.autoMerge;
     if (options.reviewEnabled !== undefined)
@@ -307,6 +336,8 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
     }
     else
         await store.saveJob(job);
+    if (job.schedule)
+        await syncScheduleLabels(client, repositoryName, job);
     return { job: await store.load(options.id), pr };
 }
 async function appendPlannedTask(store, job, task) {
@@ -494,6 +525,7 @@ async function runJobCommand(action, args) {
         objective: arg(args, '--objective') || undefined,
         priority: priority(args),
         executionMode: requestedExecutionMode(args),
+        schedule: scheduleFromArgs(args),
         autoMerge: !hasArg(args, '--no-auto-merge'),
         reviewEnabled: !hasArg(args, '--no-review'),
         continuation: continuation(args),
@@ -607,7 +639,7 @@ async function main() {
     }
     if (command === 'init') {
         const now = new Date().toISOString();
-        const job = { id: arg(args, '--id', randomUUID()), title: arg(args, '--title', 'Agents Relay job'), objective: arg(args, '--objective') || undefined, priority: priority(args), executionMode: executionMode(args), autoMerge: !hasArg(args, '--no-auto-merge'), reviewEnabled: !hasArg(args, '--no-review'), prNumber: Number(arg(args, '--pr', '0')), repository: arg(args, '--repo'), state: 'OPEN', continuation: continuation(args), createdAt: now, updatedAt: now, tasks: [] };
+        const job = { id: arg(args, '--id', randomUUID()), title: arg(args, '--title', 'Agents Relay job'), objective: arg(args, '--objective') || undefined, priority: priority(args), executionMode: executionMode(args), schedule: scheduleFromArgs(args), autoMerge: !hasArg(args, '--no-auto-merge'), reviewEnabled: !hasArg(args, '--no-review'), prNumber: Number(arg(args, '--pr', '0')), repository: arg(args, '--repo'), state: 'OPEN', continuation: continuation(args), createdAt: now, updatedAt: now, tasks: [] };
         let store;
         let file = null;
         if (arg(args, '--repo') && arg(args, '--pr'))
@@ -623,9 +655,26 @@ async function main() {
         console.log(`Initialized ${job.id}`);
         return;
     }
+    const bus = eventBus(args);
+    if (command === 'tick') {
+        const repo = repository(args);
+        const auth = await githubAuthContext(args);
+        const nowValue = arg(args, '--now');
+        const now = nowValue ? new Date(nowValue) : new Date();
+        if (Number.isNaN(now.getTime()))
+            throw new Error('--now must be a valid ISO timestamp');
+        const results = await processDueScheduledJobs({
+            client: auth.client,
+            repository: repo,
+            trustedAuthors: auth.trustedAuthors,
+            buckets: dueBuckets(now, integerArg(args, '--lookback-buckets', 3)),
+            now,
+        });
+        console.log(JSON.stringify({ repository: repo, processed: results.length, results }, null, 2));
+        return;
+    }
     const loaded = await storeFor(args);
     const { store, job, localFile } = loaded;
-    const bus = eventBus(args);
     if (command === 'agent-register') {
         const now = new Date().toISOString();
         const agent = { id: arg(args, '--agent-id', randomUUID()), name: arg(args, '--name'), responsibility: arg(args, '--responsibility'), role: arg(args, '--role'), capabilities: arg(args, '--capabilities').split(',').filter(Boolean), boundaries: arg(args, '--boundaries').split('|').filter(Boolean), endpoint: { kind: arg(args, '--endpoint-kind', 'adapter'), target: arg(args, '--endpoint') }, runtime: { adapter: arg(args, '--runtime', arg(args, '--adapter', 'shell')), provider: arg(args, '--provider') || undefined, model: arg(args, '--model') || undefined }, availability: arg(args, '--availability', 'available'), routing: { labels: arg(args, '--labels').split(',').filter(Boolean).reduce((out, item) => { const [key, value] = item.split('=', 2); if (key && value)

package/dist/events.js

@@ -50,5 +50,11 @@ export class NatsEventBus {
         })();
         return async () => { active = false; subscription.unsubscribe(); };
     }
+    async close() {
+        if (this.connection) {
+            await this.connection.close();
+            this.connection = null;
+        }
+    }
 }
 export function eventFor(jobId, taskId, parentTaskId, type, status, message, visibility = 'orchestrator', data, source) { return { version: 1, event_id: randomUUID(), job_id: jobId, task_id: taskId, parent_task_id: parentTaskId, type, status, timestamp: new Date().toISOString(), visibility, level: status === 'failed' || status === 'blocked' ? 'error' : 'info', message, data, source }; }

package/dist/reconciler.js

@@ -210,7 +210,7 @@ export class Reconciler {
         await this.store.saveJob(job);
     }
     async ensureFinalReview(job, prState, headSha) {
-        if (job.reviewEnabled === false || prState !== 'OPEN' || job.state !== 'COMPLETED' || !headSha)
+        if (job.schedule || job.reviewEnabled === false || prState !== 'OPEN' || job.state !== 'COMPLETED' || !headSha)
             return;
         if (!this.preReviewGatesPass(job))
             return;
@@ -385,31 +385,35 @@ export class Reconciler {
             return job;
         if (job.initialPlanning?.status === 'pending')
             return job;
-        const planners = job.tasks.filter(task => task.kind === 'planner').sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+        const allPlanners = job.tasks.filter(task => task.kind === 'planner').sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+        const slot = job.schedule?.currentRunSlot ? Date.parse(job.schedule.currentRunSlot) : Number.NaN;
+        const scopedTasks = Number.isFinite(slot) ? job.tasks.filter(task => Date.parse(task.createdAt) >= slot) : job.tasks;
+        const planners = scopedTasks.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'))
+        if (scopedTasks.some(task => task.state === 'FAILED' || task.state === 'BLOCKED'))
             return job;
-        if (job.tasks.length > 0 && !planners.some(task => task.state === 'SUCCEEDED'))
+        if (scopedTasks.length > 0 && !planners.some(task => task.state === 'SUCCEEDED'))
             return job;
-        if (job.tasks.some(task => task.kind !== 'planner' && !['SUCCEEDED', 'CANCELLED'].includes(task.state)))
+        if (scopedTasks.some(task => task.kind !== 'planner' && !['SUCCEEDED', 'CANCELLED'].includes(task.state)))
             return job;
         if (planners.length > 0 && planners.at(-1)?.plannerResult?.objective_status === 'in_progress' && !job.tasks.some(task => task.planningDecisionId === planners.at(-1)?.id))
             return job;
         const latest = planners.at(-1);
         if (latest?.plannerResult?.objective_status === 'satisfied')
             return job;
-        if (latest && job.review && job.review.outcome !== 'approved')
+        if (latest && !job.schedule && job.review && job.review.outcome !== 'approved')
             return job;
+        const previousPlanner = allPlanners.at(-1);
         const used = new Set(job.tasks.map(task => task.id));
-        let number = planners.length + 1;
+        let number = allPlanners.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', storySize: 'M', 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 ?? storySizeTimeoutMs('M'), createdAt: now, updatedAt: now, planningDecisionId: id, planningSource: 'model-planner', planningRound: planners.length + 1 };
+        const task = { jobId: job.id, id, kind: 'planner', storySize: 'M', agentName: 'planner', parentTaskId: previousPlanner?.id ?? null, dependencies: [], capabilities: ['planner'], adapter: 'orchestrator', input: plannerInput({ job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: previousPlanner?.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 ?? storySizeTimeoutMs('M'), createdAt: now, updatedAt: now, planningDecisionId: id, planningSource: 'model-planner', planningRound: allPlanners.length + 1 };
         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);

package/dist/scheduled-jobs.js

@@ -0,0 +1,195 @@
+import { GitHubStore, loadManagedGitHubPullRequestGraphql } from './store.js';
+import { bucketStart, nextScheduleRun, parseRunBucketLabel, runBucketLabel, scheduleBucket } from './scheduler.js';
+export const AUTONOMOUS_LABEL = 'agents-relay:autonomous';
+function searchPath(query, page) {
+    return `search/issues?q=${encodeURIComponent(query)}&sort=created&order=asc&per_page=100&page=${page}`;
+}
+export function dueBuckets(now, lookbackBuckets) {
+    if (!Number.isInteger(lookbackBuckets) || lookbackBuckets < 1 || lookbackBuckets > 36)
+        throw new Error('--lookback-buckets must be an integer from 1 to 36');
+    const result = [];
+    for (let age = lookbackBuckets - 1; age >= 0; age -= 1) {
+        result.push(scheduleBucket(new Date(bucketStart(now).getTime() - age * 600_000)));
+    }
+    return result;
+}
+export function indexedDueQuery(repository, bucket) {
+    const label = runBucketLabel(bucket);
+    return `repo:${repository} is:open is:pr label:"${AUTONOMOUS_LABEL}" label:"${label}"`;
+}
+async function issueLabels(client, repository, prNumber) {
+    const labels = [];
+    let page = 1;
+    for (;;) {
+        const response = await client.request(`repos/${repository}/issues/${prNumber}/labels?per_page=100&page=${page}`);
+        const items = Array.isArray(response) ? response : response.items;
+        if (!Array.isArray(items))
+            throw new Error(`GitHub label response for PR #${prNumber} was invalid`);
+        for (const item of items) {
+            const name = item.name;
+            if (typeof name === 'string')
+                labels.push(name);
+        }
+        if (items.length < 100)
+            return labels;
+        page += 1;
+    }
+}
+async function addLabel(client, repository, prNumber, label) {
+    await client.request(`repos/${repository}/issues/${prNumber}/labels`, {
+        method: 'POST',
+        body: JSON.stringify({ labels: [label] }),
+    });
+}
+async function removeLabel(client, repository, prNumber, label) {
+    await client.request(`repos/${repository}/issues/${prNumber}/labels/${encodeURIComponent(label)}`, { method: 'DELETE' });
+}
+async function ensureRepositoryLabel(client, repository, label, color) {
+    try {
+        await client.request(`repos/${repository}/labels/${encodeURIComponent(label)}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!/404|Not Found/i.test(message))
+            throw error;
+        await client.request(`repos/${repository}/labels`, {
+            method: 'POST',
+            body: JSON.stringify({ name: label, color }),
+        });
+    }
+}
+export async function syncScheduleLabels(client, repository, job) {
+    const current = await issueLabels(client, repository, job.prNumber);
+    const target = job.schedule ? runBucketLabel(scheduleBucket(new Date(job.schedule.nextRunAt))) : null;
+    const expected = new Set(job.schedule ? [AUTONOMOUS_LABEL, target] : []);
+    if (job.schedule || current.includes(AUTONOMOUS_LABEL))
+        await ensureRepositoryLabel(client, repository, AUTONOMOUS_LABEL, '0E8A16');
+    if (target !== null)
+        await ensureRepositoryLabel(client, repository, target, 'D4C5F9');
+    for (const label of current) {
+        const isSchedulerLabel = label === AUTONOMOUS_LABEL || parseRunBucketLabel(label) !== null || /^agents-relay:next-run:\d{8}T\d{4}Z$/.test(label);
+        if (isSchedulerLabel && !expected.has(label))
+            await removeLabel(client, repository, job.prNumber, label);
+    }
+    if (job.schedule) {
+        if (!current.includes(AUTONOMOUS_LABEL))
+            await addLabel(client, repository, job.prNumber, AUTONOMOUS_LABEL);
+        if (target !== null && !current.includes(target))
+            await addLabel(client, repository, job.prNumber, target);
+    }
+}
+const SCHEDULE_WAKE_MARKER = '<!-- agents-relay:schedule-wake:v1 -->';
+async function pulseScheduleWake(client, repository, job) {
+    const body = `${SCHEDULE_WAKE_MARKER}
+Scheduled autonomous wake for \`${job.id}\` at \`${job.schedule?.lastScheduledSlot ?? 'unknown'}\`.`;
+    let page = 1;
+    for (;;) {
+        const response = await client.request(`repos/${repository}/issues/${job.prNumber}/comments?per_page=100&page=${page}`);
+        const items = Array.isArray(response) ? response : [];
+        const existing = items.find(item => typeof item.body === 'string' && String(item.body).includes(SCHEDULE_WAKE_MARKER));
+        if (existing && Number.isInteger(Number(existing.id))) {
+            await client.request(`repos/${repository}/issues/comments/${Number(existing.id)}`, { method: 'PATCH', body: JSON.stringify({ body }) });
+            return;
+        }
+        if (items.length < 100)
+            break;
+        page += 1;
+    }
+    await client.request(`repos/${repository}/issues/${job.prNumber}/comments`, { method: 'POST', body: JSON.stringify({ body }) });
+}
+export async function listIndexedScheduledJobs(client, repository, trustedAuthors, buckets) {
+    const found = new Map();
+    const seenPrs = new Set();
+    for (const bucket of buckets) {
+        const query = indexedDueQuery(repository, bucket);
+        for (let page = 1; page <= 10; page += 1) {
+            const response = await client.request(searchPath(query, page));
+            const items = Array.isArray(response?.items) ? response.items : [];
+            for (const item of items) {
+                const prNumber = Number(item.number);
+                if (!Number.isInteger(prNumber) || prNumber <= 0 || seenPrs.has(prNumber))
+                    continue;
+                seenPrs.add(prNumber);
+                const overviews = await loadManagedGitHubPullRequestGraphql(client, repository, prNumber, trustedAuthors).catch((error) => {
+                    if (error instanceof Error && error.message.includes('has no durable'))
+                        return [];
+                    throw error;
+                });
+                const job = overviews.find(overview => overview.githubState === 'OPEN' && overview.job.schedule !== undefined)?.job;
+                if (!job?.schedule)
+                    continue;
+                const slotBucket = scheduleBucket(new Date(job.schedule.nextRunAt));
+                if (!buckets.includes(slotBucket))
+                    continue;
+                found.set(`${prNumber}:${job.id}`, { prNumber, jobId: job.id, bucket: slotBucket });
+            }
+            if (items.length < 100)
+                break;
+        }
+    }
+    return [...found.values()];
+}
+async function refresh(client, repository, trustedAuthors, ref) {
+    const store = new GitHubStore(client, repository, ref.prNumber, trustedAuthors);
+    return await store.load(ref.jobId);
+}
+export async function runScheduledBucket(client, repository, trustedAuthors, ref, engine, now = new Date()) {
+    let job = await refresh(client, repository, trustedAuthors, ref);
+    const schedule = job.schedule;
+    if (!schedule)
+        throw new Error(`Scheduled job ${job.id} has no schedule metadata`);
+    const slot = new Date(schedule.nextRunAt);
+    if (scheduleBucket(slot) !== ref.bucket || slot.getTime() > now.getTime()) {
+        await syncScheduleLabels(client, repository, job);
+        return { job, status: 'skipped-idempotent' };
+    }
+    if (schedule.lastScheduledSlot && new Date(schedule.lastScheduledSlot).getTime() >= slot.getTime()) {
+        await syncScheduleLabels(client, repository, job);
+        return { job, status: 'skipped-idempotent' };
+    }
+    const active = job.state === 'RUNNING' || job.tasks.some(task => ['READY', 'RUNNING'].includes(task.state));
+    if (active && schedule.concurrencyPolicy === 'skip') {
+        schedule.lastScheduledSlot = slot.toISOString();
+        schedule.nextRunAt = nextScheduleRun(schedule, now).toISOString();
+        job.updatedAt = now.toISOString();
+        await new GitHubStore(client, repository, ref.prNumber, trustedAuthors).saveJob(job);
+        await syncScheduleLabels(client, repository, job);
+        return { job, status: 'skipped-active' };
+    }
+    if (active && schedule.concurrencyPolicy === 'queue') {
+        await syncScheduleLabels(client, repository, job);
+        return { job, status: 'skipped-active' };
+    }
+    const missedRunPolicy = schedule.missedRunPolicy;
+    schedule.lastScheduledSlot = slot.toISOString();
+    schedule.currentRunSlot = slot.toISOString();
+    schedule.nextRunAt = nextScheduleRun(schedule, missedRunPolicy === 'run' ? slot : now).toISOString();
+    job.updatedAt = now.toISOString();
+    const schedulerStore = new GitHubStore(client, repository, ref.prNumber, trustedAuthors);
+    job.state = 'RUNNING';
+    await schedulerStore.saveJob(job);
+    job = await schedulerStore.load(job.id);
+    await syncScheduleLabels(client, repository, job);
+    if (engine) {
+        await engine.reconcile(job.id);
+        await engine.idle();
+        const finished = await schedulerStore.load(job.id);
+        if (!finished.schedule)
+            throw new Error(`Scheduled job ${job.id} lost its schedule metadata`);
+        finished.schedule.lastRunAt = now.toISOString();
+        finished.updatedAt = now.toISOString();
+        await schedulerStore.saveJob(finished);
+        return { job: finished, status: 'completed' };
+    }
+    await pulseScheduleWake(client, repository, job);
+    return { job, status: 'dispatched' };
+}
+export async function processDueScheduledJobs(options) {
+    const due = await listIndexedScheduledJobs(options.client, options.repository, options.trustedAuthors, options.buckets);
+    const results = [];
+    for (const ref of due) {
+        const engine = options.engine ? options.engine(await refresh(options.client, options.repository, options.trustedAuthors, ref)) : undefined;
+        results.push(await runScheduledBucket(options.client, options.repository, options.trustedAuthors, ref, engine, options.now));
+    }
+    return results;
+}

package/dist/scheduler.js

@@ -5,7 +5,15 @@ export function detectCycles(tasks) { const map = new Map(tasks.map(t => [t.id,
     return; visiting.add(id); for (const dep of map.get(id)?.dependencies ?? [])
     visit(dep); visiting.delete(id); done.add(id); }; for (const task of tasks)
     visit(task.id); }
+function scheduledCycleTasks(job) {
+    const slot = job.schedule?.currentRunSlot ? Date.parse(job.schedule.currentRunSlot) : Number.NaN;
+    if (!Number.isFinite(slot))
+        return job.tasks;
+    return job.tasks.filter(task => Date.parse(task.createdAt) >= slot);
+}
 export function completionGateSatisfied(job) {
+    if (job.schedule)
+        return false;
     if (job.executionMode !== 'autonomous')
         return true;
     const planners = job.tasks.filter(task => task.kind === 'planner');
@@ -13,7 +21,8 @@ export function completionGateSatisfied(job) {
 }
 export function schedule(job) {
     detectCycles(job.tasks);
-    if (job.tasks.length === 0) {
+    const scopedTasks = scheduledCycleTasks(job);
+    if (scopedTasks.length === 0) {
         if (job.executionMode === 'autonomous' && job.state !== 'WAITING') {
             assertJobTransition(job.state, 'WAITING');
             job.state = 'WAITING';
@@ -22,16 +31,27 @@ export function schedule(job) {
         return job;
     }
     const map = new Map(job.tasks.map(t => [t.id, t]));
-    for (const task of job.tasks) {
+    for (const task of scopedTasks) {
         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 active = scopedTasks.some(t => ['READY', 'RUNNING'].includes(t.state));
+    const blocked = scopedTasks.some(t => t.state === 'BLOCKED');
+    const waiting = scopedTasks.some(t => ['QUEUED', 'WAITING'].includes(t.state));
+    const failed = scopedTasks.some(t => t.state === 'FAILED');
+    const cancelled = scopedTasks.every(t => t.state === 'CANCELLED');
     const next = active ? 'RUNNING' : failed ? 'FAILED' : blocked ? 'BLOCKED' : waiting ? 'WAITING' : cancelled ? 'CANCELLED' : completionGateSatisfied(job) ? 'COMPLETED' : 'WAITING';
+    if (job.schedule && next === 'WAITING') {
+        const planners = scopedTasks.filter(task => task.kind === 'planner');
+        const latest = planners.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id)).at(-1);
+        if (latest?.state === 'SUCCEEDED' && latest.plannerResult?.objective_status === 'satisfied') {
+            const slot = job.schedule.currentRunSlot ? Date.parse(job.schedule.currentRunSlot) : Number.NaN;
+            const lastRun = job.schedule.lastRunAt ? Date.parse(job.schedule.lastRunAt) : Number.NaN;
+            if (Number.isFinite(slot) && (!Number.isFinite(lastRun) || lastRun < slot))
+                job.schedule.lastRunAt = new Date().toISOString();
+            job.schedule.currentRunSlot = null;
+        }
+    }
     if (job.state !== next) {
         assertJobTransition(job.state, next);
         job.state = next;
@@ -47,3 +67,149 @@ export function extendRetryBudget(task, windowSize = 3) {
 }
 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(); }
+export const SCHEDULE_RESOLUTION_MS = 600_000;
+export const RUN_BUCKET_LABEL_COUNT = 144;
+const CRON_PART = /^(?:\*|(\d+)(?:-(\d+))?)(?:\/(\d+))?$/;
+function cronField(raw, name, minimum, maximum) {
+    const values = new Set();
+    for (const part of raw.split(',')) {
+        const match = CRON_PART.exec(part);
+        if (!match)
+            throw new Error(`Invalid schedule ${name}: ${part}`);
+        const [whole, firstText, lastText, stepText] = match;
+        if (whole === undefined)
+            continue;
+        const step = stepText === undefined ? 1 : Number(stepText);
+        if (!Number.isInteger(step) || step < 1)
+            throw new Error(`Invalid schedule ${name} step: ${part}`);
+        let start = minimum;
+        let end = maximum;
+        if (firstText !== undefined) {
+            start = Number(firstText);
+            end = lastText === undefined ? (stepText === undefined ? start : maximum) : Number(lastText);
+            if (start < minimum || end > maximum || start > end)
+                throw new Error(`Invalid schedule ${name} range: ${part}`);
+        }
+        for (let value = start; value <= end; value += step) {
+            if (value > maximum)
+                break;
+            values.add(name === 'weekday' && value === 7 ? 0 : value);
+        }
+    }
+    if (values.size === 0)
+        throw new Error(`Invalid schedule ${name}: ${raw}`);
+    return values;
+}
+export function parseCron(cron) {
+    const fields = cron.trim().split(/\s+/);
+    if (fields.length !== 5)
+        throw new Error('Schedule cron must contain exactly five fields');
+    const parsed = {
+        minute: cronField(fields[0], 'minute', 0, 59),
+        hour: cronField(fields[1], 'hour', 0, 23),
+        dayOfMonth: cronField(fields[2], 'day-of-month', 1, 31),
+        month: cronField(fields[3], 'month', 1, 12),
+        weekday: cronField(fields[4], 'weekday', 0, 7),
+    };
+    for (const minute of parsed.minute)
+        if (minute % (SCHEDULE_RESOLUTION_MS / 60_000) !== 0)
+            throw new Error(`Schedule minute ${minute} is finer than the 10-minute scheduler resolution`);
+    return parsed;
+}
+function timezoneParts(time, timeZone) {
+    const parts = new Intl.DateTimeFormat('en-US', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', weekday: 'short', hourCycle: 'h23' }).formatToParts(time);
+    const value = (type) => parts.find(part => part.type === type)?.value ?? '';
+    const weekdays = new Map([['Sun', 0], ['Mon', 1], ['Tue', 2], ['Wed', 3], ['Thu', 4], ['Fri', 5], ['Sat', 6]]);
+    const weekday = weekdays.get(value('weekday'));
+    if (weekday === undefined)
+        throw new Error(`Unable to resolve timezone weekday ${timeZone}`);
+    return { year: Number(value('year')), month: Number(value('month')), day: Number(value('day')), hour: Number(value('hour')), minute: Number(value('minute')), weekday };
+}
+function cronMatches(fields, time, timeZone) {
+    const local = timezoneParts(time, timeZone);
+    if (!fields.minute.has(local.minute) || !fields.hour.has(local.hour) || !fields.month.has(local.month))
+        return false;
+    const domWildcard = fields.dayOfMonth.size === 31;
+    const dowWildcard = fields.weekday.size === 7;
+    const domMatch = fields.dayOfMonth.has(local.day);
+    const dowMatch = fields.weekday.has(local.weekday);
+    const dayMatch = domWildcard && dowWildcard ? true : domWildcard ? dowMatch : dowWildcard ? domMatch : domMatch || dowMatch;
+    return dayMatch;
+}
+export function nextCronRun(cron, timeZone, after = new Date()) {
+    const fields = parseCron(cron);
+    if (!isValidTimeZone(timeZone))
+        throw new Error(`Invalid schedule timezone: ${timeZone}`);
+    const candidate = new Date(Math.floor((after.getTime() + 60_000) / 60_000) * 60_000);
+    const limit = candidate.getTime() + 366 * 24 * 60 * 60_000;
+    while (candidate.getTime() < limit) {
+        if (cronMatches(fields, candidate, timeZone))
+            return new Date(candidate);
+        candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);
+    }
+    throw new Error(`Schedule ${cron} has no next run within one year`);
+}
+export function isValidTimeZone(timeZone) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function parseJobSchedule(options) {
+    const fields = parseCron(options.cron);
+    if (!isValidTimeZone(options.timezone))
+        throw new Error(`Invalid schedule timezone: ${options.timezone}`);
+    const missedRunPolicy = options.missedRunPolicy ?? 'skip';
+    const concurrencyPolicy = options.concurrencyPolicy ?? 'skip';
+    if (!['run', 'skip'].includes(missedRunPolicy))
+        throw new Error('Invalid missed-run policy');
+    if (!['skip', 'queue'].includes(concurrencyPolicy))
+        throw new Error('Invalid schedule concurrency policy');
+    const next = options.nextRunAt ? new Date(options.nextRunAt) : nextCronRun(options.cron, options.timezone);
+    if (Number.isNaN(next.getTime()))
+        throw new Error('Invalid schedule next-run time');
+    const aligned = new Date(Math.floor(next.getTime() / 60_000) * 60_000);
+    if (!cronMatches(fields, aligned, options.timezone))
+        throw new Error('Schedule next-run time does not match the cron expression');
+    return {
+        cron: options.cron.trim(),
+        timezone: options.timezone,
+        nextRunAt: aligned.toISOString(),
+        missedRunPolicy,
+        concurrencyPolicy,
+        lastScheduledSlot: null,
+        currentRunSlot: null,
+        lastRunAt: null,
+    };
+}
+export function nextScheduleRun(schedule, after = new Date()) {
+    return nextCronRun(schedule.cron, schedule.timezone, after);
+}
+export function bucketStart(time = new Date()) {
+    return new Date(Math.floor(time.getTime() / SCHEDULE_RESOLUTION_MS) * SCHEDULE_RESOLUTION_MS);
+}
+export function scheduleBucket(time) {
+    const bucket = bucketStart(time);
+    return `${bucket.toISOString().slice(0, 4)}${bucket.toISOString().slice(5, 7)}${bucket.toISOString().slice(8, 10)}T${bucket.toISOString().slice(11, 13)}${bucket.toISOString().slice(14, 16)}Z`;
+}
+export function runBucketLabel(bucket) {
+    if (!/^\d{8}T\d{4}Z$/.test(bucket))
+        throw new Error(`Invalid schedule bucket: ${bucket}`);
+    const hour = Number(bucket.slice(9, 11));
+    const minute = Number(bucket.slice(11, 13));
+    const slot = hour * 6 + minute / 10;
+    return `agents-relay:next-run:${slot}`;
+}
+export function parseRunBucketLabel(label) {
+    const prefix = 'agents-relay:next-run:';
+    if (!label.startsWith(prefix))
+        return null;
+    const value = label.slice(prefix.length);
+    if (!/^\d{1,3}$/.test(value))
+        return null;
+    const slot = Number(value);
+    return Number.isInteger(slot) && slot >= 0 && slot < RUN_BUCKET_LABEL_COUNT ? value : null;
+}

package/package.json

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

package/skills/agents-relay/contracts/task-job-contract.md

@@ -43,3 +43,5 @@ Final-review routing follows the same worker-selection boundary as executable wo
 ## Fixed and autonomous jobs
 
 `fixed` jobs execute the orchestrator-provided task set and then proceed to final review. `autonomous` jobs may ask the planner for additional task batches. Planner-produced tasks must obey this same contract, including explicit `storySize`.
+
+A scheduled autonomous job adds cron/timezone/next-run and missed-run/concurrency policy to the trusted job marker, plus the `agents-relay:autonomous` label and one bounded time-of-day `agents-relay:next-run:*` index label. The GitHub heartbeat discovers only indexed due candidates, validates the marker's exact `nextRunAt`, claims the slot idempotently, advances the durable next run, and pulses `agents-relay:schedule-wake`. GitHub webhook delivery then wakes local Relay for planner/worker execution. While the schedule is active, each satisfied run returns the job to `WAITING` instead of entering final-review/auto-merge; older-cycle failures are historical evidence and do not block a later slot.