@abot-ai/runtime 1.5.0 → 1.7.0

package/dist/src/runtime/scheduler/automation-job-management.js

@@ -0,0 +1,288 @@
+import { randomUUID } from "node:crypto";
+import { requireUnarchivedAutomation } from "../automations/archive-management.js";
+import { publishedAutomationScheduleTiming } from "../automations/trigger-schedule.js";
+import { normalizeAutomationSchedule, requireAutomationScheduleOccurrence, hasAutomationScheduleTimingChanged } from "./automation-schedule.js";
+import { hasReachedAutomationDailyRunLimit } from "./automation-run-budget.js";
+import { findPendingAutomationRun, hasActiveAutomationRun, makeAutomationSchedulerRun, requireAutomationSchedulerJob, } from "./automation-run-records.js";
+import { nextSchedulerOccurrence } from "./next-occurrence.js";
+import { canBeginSchedulerRun, invalidateJob, jobEpoch, requireRunningScheduler, } from "./service-context.js";
+import { validateTimeZone } from "./schedule-validation.js";
+import { isAutomationSchedulerJob, isAutomationSchedulerRun, } from "./scheduler-target.js";
+function requireAutomationJournalUpdate(context) {
+    const update = context.store.updateWithAutomations;
+    if (!update)
+        throw new Error("automation_store_unavailable");
+    return update;
+}
+function requireAutomationExecutor(context) {
+    const executor = context.automationExecutor;
+    if (!executor)
+        throw new Error("automation_executor_unavailable");
+    return executor;
+}
+function requireAutomationJobInput(input) {
+    if (!input.automationId?.trim())
+        throw new Error("automation_invalid_job");
+    if (!input.title?.trim())
+        throw new Error("automation_invalid_job");
+    if (!Number.isSafeInteger(input.definitionRevision))
+        throw new Error("automation_invalid_job");
+    if (input.definitionRevision < 1)
+        throw new Error("automation_invalid_job");
+    validateTimeZone(input.timeZone);
+}
+export function createAutomationSchedulerJob(context, input, commitPublication) {
+    return context.enqueue(async () => {
+        requireRunningScheduler(context);
+        requireAutomationJobInput(input);
+        const now = context.now();
+        const schedule = normalizeAutomationSchedule(input.schedule, now);
+        const nextRunAt = requireAutomationScheduleOccurrence(schedule, input.timeZone, now);
+        const job = {
+            id: randomUUID(),
+            environmentId: context.environmentId,
+            target: {
+                kind: "automation",
+                automationId: input.automationId,
+                definitionRevision: input.definitionRevision,
+            },
+            title: input.title.trim(),
+            timeZone: input.timeZone,
+            schedule,
+            state: "paused",
+            createdAt: new Date(now).toISOString(),
+            updatedAt: new Date(now).toISOString(),
+            nextRunAt,
+            revision: 1,
+        };
+        const update = requireAutomationJournalUpdate(context);
+        return update((scheduler, automations) => {
+            requireUnarchivedAutomation(automations, input.automationId);
+            if (hasAutomationJob(scheduler, input.automationId))
+                throw new Error("automation_job_exists");
+            commitPublication?.(automations, job);
+            scheduler.jobs.push(job);
+            return job;
+        });
+    });
+}
+function hasAutomationJob(scheduler, automationId) {
+    return scheduler.jobs.some((job) => isAutomationSchedulerJob(job) &&
+        job.target.automationId === automationId);
+}
+export function updateAutomationSchedulerJob(context, jobId, patch, commitPublication) {
+    const settleInvalidation = invalidateJob(context, jobId);
+    return context
+        .enqueue(async () => {
+        requireRunningScheduler(context);
+        const update = requireAutomationJournalUpdate(context);
+        return update((scheduler, automations) => {
+            const job = requireAutomationSchedulerJob(scheduler, jobId);
+            requireUnarchivedAutomation(automations, job.target.automationId);
+            if (job.state === "cancelled")
+                throw new Error("scheduler_job_cancelled");
+            const now = context.now();
+            const draft = automations.drafts.find((item) => item.automationId === job.target.automationId &&
+                item.revision === patch.definitionRevision);
+            const previousTiming = commitPublication
+                ? publishedAutomationScheduleTiming(automations, job, draft?.definition.trigger) : undefined;
+            const candidate = updatedAutomationJob(job, patch, now, previousTiming);
+            commitPublication?.(automations, candidate);
+            if (JSON.stringify(candidate) === JSON.stringify(job))
+                return job;
+            cancelPendingAutomationRuns(context, scheduler, automations, jobId, now, "republished");
+            Object.assign(job, candidate);
+            return job;
+        });
+    })
+        .finally(settleInvalidation);
+}
+function updatedAutomationJob(job, patch, now, previousTiming) {
+    const title = patch.title ?? job.title;
+    const timeZone = patch.timeZone ?? job.timeZone;
+    const definitionRevision = patch.definitionRevision ?? job.target.definitionRevision;
+    requireAutomationJobInput({
+        automationId: job.target.automationId,
+        title,
+        timeZone,
+        definitionRevision,
+        schedule: patch.schedule ?? job.schedule,
+    });
+    if (definitionRevision < job.target.definitionRevision)
+        throw new Error("automation_definition_revision_regressed");
+    const schedule = patch.schedule
+        ? normalizeAutomationSchedule(patch.schedule, now, previousTiming)
+        : job.schedule;
+    const timingChanged = hasAutomationScheduleTimingChanged(schedule, timeZone, job);
+    const nextRunAt = timingChanged
+        ? requireAutomationScheduleOccurrence(schedule, timeZone, now)
+        : job.nextRunAt;
+    const changed = title !== job.title ||
+        timeZone !== job.timeZone ||
+        definitionRevision !== job.target.definitionRevision ||
+        timingChanged;
+    if (!changed)
+        return job;
+    return {
+        ...job,
+        target: { ...job.target, definitionRevision },
+        title: title.trim(),
+        timeZone,
+        schedule,
+        nextRunAt,
+        updatedAt: new Date(now).toISOString(),
+        revision: job.revision + 1,
+        state: job.state === "completed" && timingChanged ? "active" : job.state,
+    };
+}
+function cancelPendingAutomationRuns(context, scheduler, automations, jobId, now, reason) {
+    const at = new Date(now).toISOString();
+    for (const run of scheduler.runs) {
+        if (run.jobId !== jobId || run.status !== "pending")
+            continue;
+        if (!isAutomationSchedulerRun(run))
+            continue;
+        requireAutomationExecutor(context).cancelPending(run, automations, reason);
+        const execution = requireCommittedAutomationExecution(automations, run.id);
+        if (!execution.reportRef)
+            throw new Error("automation_report_missing");
+        run.status = "cancelled";
+        run.reportRef = execution.reportRef;
+        run.finishedAt = at;
+    }
+}
+export function changeAutomationSchedulerJobState(context, jobId, target) {
+    const settleInvalidation = invalidateJob(context, jobId);
+    return context
+        .enqueue(async () => {
+        requireRunningScheduler(context);
+        const update = requireAutomationJournalUpdate(context);
+        return update((scheduler, automations) => {
+            const job = requireAutomationSchedulerJob(scheduler, jobId);
+            if (job.state === "cancelled")
+                throw new Error("scheduler_job_cancelled");
+            const now = context.now();
+            if (target === "active")
+                requireUnarchivedAutomation(automations, job.target.automationId);
+            if (target === "paused") {
+                cancelPendingAutomationRuns(context, scheduler, automations, jobId, now, "paused");
+            }
+            if (job.state === target)
+                return job;
+            job.state = target;
+            job.updatedAt = new Date(now).toISOString();
+            job.revision += 1;
+            if (target !== "active")
+                return job;
+            job.nextRunAt = nextSchedulerOccurrence(job.schedule, job.timeZone, now);
+            if (hasExhaustedAutomationSchedule(job))
+                job.state = "completed";
+            return job;
+        });
+    })
+        .finally(settleInvalidation);
+}
+function hasExhaustedAutomationSchedule(job) {
+    if (job.schedule.kind === "manual")
+        return false;
+    return job.nextRunAt === null;
+}
+export function requestAutomationSchedulerRunNow(context, jobId, options) {
+    return context.enqueue(async () => {
+        requireRunningScheduler(context);
+        const idempotencyKey = options?.idempotencyKey;
+        if (idempotencyKey !== undefined &&
+            (!idempotencyKey || idempotencyKey.length > 128))
+            throw new Error("automation_idempotency_key_invalid");
+        const scheduler = await context.store.read();
+        const job = requireAutomationSchedulerJob(scheduler, jobId);
+        if (job.state === "cancelled")
+            throw new Error("scheduler_job_cancelled");
+        if (!context.store.readAutomations)
+            throw new Error("automation_store_unavailable");
+        requireUnarchivedAutomation(await context.store.readAutomations(), job.target.automationId);
+        if (idempotencyKey) {
+            const readByKey = context.store.readAutomationRunByKey;
+            if (!readByKey)
+                throw new Error("automation_idempotency_unavailable");
+            const previous = await readByKey(job.target.automationId, idempotencyKey);
+            if (previous) {
+                if (previous.replayOf || previous.jobId !== job.id ||
+                    previous.target.definitionRevision !== job.target.definitionRevision)
+                    throw new Error("automation_idempotency_conflict");
+                return previous;
+            }
+        }
+        const pending = findPendingAutomationRun(scheduler, jobId);
+        if (pending) {
+            if (idempotencyKey)
+                throw new Error("automation_run_active");
+            return pending;
+        }
+        if (hasActiveAutomationRun(scheduler, job.target.automationId))
+            throw new Error("automation_run_active");
+        const executor = requireAutomationExecutor(context);
+        const candidateId = randomUUID();
+        const epoch = jobEpoch(context, jobId);
+        const prepared = await executor.prepare(job, candidateId, "manual");
+        if (prepared.kind === "no_input") {
+            if (prepared.commit) {
+                const update = requireAutomationJournalUpdate(context);
+                await update((current, automations) => {
+                    if (!canBeginSchedulerRun(context, jobId, epoch))
+                        throw new Error("automation_job_changed");
+                    const live = requireAutomationSchedulerJob(current, jobId);
+                    requireUnarchivedAutomation(automations, live.target.automationId);
+                    if (live.revision !== job.revision)
+                        throw new Error("automation_job_changed");
+                    prepared.commit?.(automations);
+                });
+            }
+            throw new Error("automation_no_eligible_input");
+        }
+        let claimed = false;
+        try {
+            const update = requireAutomationJournalUpdate(context);
+            if (await hasReachedAutomationDailyRunLimit(context, job, context.now()))
+                throw new Error("automation_budget_exhausted");
+            const run = await update((current, automations) => {
+                if (!canBeginSchedulerRun(context, jobId, epoch))
+                    throw new Error("automation_job_changed");
+                const live = requireAutomationSchedulerJob(current, jobId);
+                requireUnarchivedAutomation(automations, live.target.automationId);
+                if (live.revision !== job.revision)
+                    throw new Error("automation_job_changed");
+                if (hasActiveAutomationRun(current, live.target.automationId))
+                    throw new Error("automation_run_active");
+                const run = makeAutomationSchedulerRun(live, candidateId, new Date(context.now()).toISOString(), "manual", idempotencyKey);
+                prepared.commit(automations, run.id);
+                const execution = requireCommittedAutomationExecution(automations, run.id);
+                if (prepared.kind === "failed") {
+                    if (!execution.reportRef)
+                        throw new Error("automation_report_missing");
+                    run.status = "failed";
+                    run.error = prepared.error;
+                    run.reportRef = execution.reportRef;
+                    run.finishedAt = new Date(context.now()).toISOString();
+                    live.state = "paused";
+                    live.updatedAt = run.finishedAt;
+                    live.revision += 1;
+                }
+                current.runs.push(run);
+                return run;
+            });
+            claimed = true;
+            return run;
+        }
+        finally {
+            if (!claimed && prepared.kind === "ready")
+                await prepared.discard?.();
+        }
+    });
+}
+export function requireCommittedAutomationExecution(state, runId) {
+    const execution = state.executions.find((item) => item.id === runId);
+    if (!execution)
+        throw new Error("automation_execution_checkpoint_missing");
+    return execution;
+}

package/dist/src/runtime/scheduler/automation-rerun.d.ts

@@ -0,0 +1,6 @@
+import type { SchedulerAutomationRun } from "./contracts.js";
+import { type SchedulerContext } from "./service-context.js";
+import type { SchedulerService } from "./contracts.js";
+type RerunOptions = Parameters<SchedulerService["rerunAutomationRun"]>[1];
+export declare function requestAutomationSchedulerRerun(context: SchedulerContext, previousRunId: string, options: RerunOptions): Promise<SchedulerAutomationRun>;
+export {};

package/dist/src/runtime/scheduler/automation-rerun.js

@@ -0,0 +1,95 @@
+import { randomUUID } from "node:crypto";
+import { requireUnarchivedAutomation } from "../automations/archive-management.js";
+import { requireCommittedAutomationExecution } from "./automation-job-management.js";
+import { hasReachedAutomationDailyRunLimit } from "./automation-run-budget.js";
+import { hasActiveAutomationRun, makeAutomationSchedulerRun, requireAutomationSchedulerJob, } from "./automation-run-records.js";
+import { canBeginSchedulerRun, jobEpoch, requireRunningScheduler, } from "./service-context.js";
+import { isAutomationSchedulerRun } from "./scheduler-target.js";
+function requireReplayableRun(run) {
+    if (!run || !isAutomationSchedulerRun(run))
+        throw new Error("automation_run_not_found");
+    if (["pending", "running", "stopping"].includes(run.status))
+        throw new Error("automation_run_active");
+    if (!run.reportRef)
+        throw new Error("automation_report_missing");
+    return run;
+}
+function replayJob(current, previous) {
+    return {
+        ...current,
+        target: { ...current.target, definitionRevision: previous.target.definitionRevision },
+    };
+}
+export function requestAutomationSchedulerRerun(context, previousRunId, options) {
+    return context.enqueue(async () => {
+        requireRunningScheduler(context);
+        if (options?.confirmed !== true ||
+            typeof options.idempotencyKey !== "string" ||
+            !options.idempotencyKey || options.idempotencyKey.length > 128 ||
+            typeof options.validateAdmission !== "function")
+            throw new Error("automation_rerun_confirmation_required");
+        const readRun = context.store.readRun;
+        const readByKey = context.store.readAutomationRunByKey;
+        const update = context.store.updateWithAutomations;
+        const executor = context.automationExecutor;
+        if (!readRun || !readByKey || !update || !executor?.prepareReplay)
+            throw new Error("automation_rerun_unavailable");
+        const previous = requireReplayableRun(await readRun(previousRunId));
+        const scheduler = await context.store.read();
+        const job = requireAutomationSchedulerJob(scheduler, previous.jobId);
+        if (job.state === "cancelled" ||
+            job.target.automationId !== previous.target.automationId)
+            throw new Error("automation_job_not_found");
+        if (!context.store.readAutomations)
+            throw new Error("automation_store_unavailable");
+        requireUnarchivedAutomation(await context.store.readAutomations(), job.target.automationId);
+        const existing = await readByKey(previous.target.automationId, options.idempotencyKey);
+        if (existing) {
+            if (existing.replayOf !== previous.id || existing.jobId !== job.id)
+                throw new Error("automation_idempotency_conflict");
+            return existing;
+        }
+        if (hasActiveAutomationRun(scheduler, job.target.automationId))
+            throw new Error("automation_run_active");
+        await options.preflight?.(job, previous);
+        if (await hasReachedAutomationDailyRunLimit(context, job, context.now()))
+            throw new Error("automation_budget_exhausted");
+        const candidateRunId = randomUUID();
+        const epoch = jobEpoch(context, job.id);
+        const prepared = await executor.prepareReplay(replayJob(job, previous), previous, candidateRunId);
+        if (prepared.kind !== "ready")
+            throw new Error("automation_replay_input_unavailable");
+        let claimed = false;
+        try {
+            const run = await update((current, automations) => {
+                if (!canBeginSchedulerRun(context, job.id, epoch))
+                    throw new Error("automation_job_changed");
+                const live = requireAutomationSchedulerJob(current, job.id);
+                requireUnarchivedAutomation(automations, live.target.automationId);
+                if (live.revision !== job.revision)
+                    throw new Error("automation_job_changed");
+                if (hasActiveAutomationRun(current, live.target.automationId))
+                    throw new Error("automation_run_active");
+                options.validateAdmission(automations, live, previous);
+                const run = {
+                    ...makeAutomationSchedulerRun(replayJob(live, previous), candidateRunId, new Date(context.now()).toISOString(), "manual", options.idempotencyKey),
+                    replayOf: previous.id,
+                };
+                prepared.commit(automations, run.id);
+                const execution = requireCommittedAutomationExecution(automations, run.id);
+                if (execution.definitionRevision !== previous.target.definitionRevision ||
+                    execution.inputIds.length !== prepared.inputIds.length ||
+                    execution.inputIds.some((id, index) => id !== prepared.inputIds[index]))
+                    throw new Error("automation_execution_checkpoint_mismatch");
+                current.runs.push(run);
+                return run;
+            });
+            claimed = true;
+            return run;
+        }
+        finally {
+            if (!claimed)
+                await prepared.discard?.();
+        }
+    });
+}

package/dist/src/runtime/scheduler/automation-run-budget.d.ts

@@ -0,0 +1,4 @@
+import type { SchedulerAutomationJob } from "./contracts.js";
+import type { SchedulerContext } from "./service-context.js";
+/** Counts admitted Runs on the Job's local calendar day across all revisions. */
+export declare function hasReachedAutomationDailyRunLimit(context: SchedulerContext, job: SchedulerAutomationJob, at: number): Promise<boolean>;

package/dist/src/runtime/scheduler/automation-run-budget.js

@@ -0,0 +1,16 @@
+/** Counts admitted Runs on the Job's local calendar day across all revisions. */
+export async function hasReachedAutomationDailyRunLimit(context, job, at) {
+    const read = context.store.readAutomations;
+    if (!read)
+        throw new Error("automation_store_unavailable");
+    const state = await read();
+    const definition = state.definitions.find((item) => item.automationId === job.target.automationId &&
+        item.revision === job.target.definitionRevision)?.definition;
+    if (!definition)
+        return false; // Preparation records the missing revision once.
+    const count = context.store.countAutomationRunsOnDay;
+    if (!count)
+        throw new Error("automation_run_budget_unavailable");
+    const admitted = await count(job.target.automationId, job.timeZone, at);
+    return admitted >= definition.limits.maxRunsPerDay;
+}

package/dist/src/runtime/scheduler/automation-run-change-events.d.ts

@@ -0,0 +1,11 @@
+import type { SchedulerAutomationRun, SchedulerStore } from "./contracts.js";
+export type AutomationRunChange = Readonly<{
+    phase: "started" | "finished";
+    environmentId: string;
+    automationId: string;
+    runId: string;
+    title: string;
+    status: SchedulerAutomationRun["status"];
+}>;
+/** Publish only transitions whose scheduler transaction committed successfully. */
+export declare function observeAutomationRunChanges(store: SchedulerStore, onChange: (change: AutomationRunChange) => void): SchedulerStore;

package/dist/src/runtime/scheduler/automation-run-change-events.js

@@ -0,0 +1,77 @@
+import { isAutomationSchedulerRun } from "./scheduler-target.js";
+function isTerminalAutomationRun(status) {
+    return ["succeeded", "completed_with_skips", "failed", "cancelled", "interrupted", "missed"]
+        .includes(status);
+}
+function automationRunChangePhase(status) {
+    if (status === "running")
+        return "started";
+    if (isTerminalAutomationRun(status))
+        return "finished";
+    return null;
+}
+function automationRunStatuses(state) {
+    return new Map(state.runs.filter(isAutomationSchedulerRun)
+        .map((run) => [run.id, run.status]));
+}
+function changedAutomationRuns(previous, state) {
+    const changes = [];
+    for (const run of state.runs) {
+        if (!isAutomationSchedulerRun(run))
+            continue;
+        if (previous.get(run.id) === run.status)
+            continue;
+        const phase = automationRunChangePhase(run.status);
+        if (!phase)
+            continue;
+        changes.push({
+            phase,
+            environmentId: run.environmentId,
+            automationId: run.target.automationId,
+            runId: run.id,
+            title: run.title,
+            status: run.status,
+        });
+    }
+    return changes;
+}
+/** Publish only transitions whose scheduler transaction committed successfully. */
+export function observeAutomationRunChanges(store, onChange) {
+    function publish(changes) {
+        for (const change of changes) {
+            try {
+                onChange(change);
+            }
+            catch {
+                // A notification observer cannot change the result of a durable commit.
+            }
+        }
+    }
+    return {
+        ...store,
+        async update(mutate, view) {
+            let changes = [];
+            const result = await store.update((state) => {
+                const previous = automationRunStatuses(state);
+                const value = mutate(state);
+                changes = changedAutomationRuns(previous, state);
+                return value;
+            }, view);
+            publish(changes);
+            return result;
+        },
+        ...(store.updateWithAutomations ? {
+            async updateWithAutomations(mutate, view) {
+                let changes = [];
+                const result = await store.updateWithAutomations((scheduler, automations) => {
+                    const previous = automationRunStatuses(scheduler);
+                    const value = mutate(scheduler, automations);
+                    changes = changedAutomationRuns(previous, scheduler);
+                    return value;
+                }, view);
+                publish(changes);
+                return result;
+            },
+        } : {}),
+    };
+}

package/dist/src/runtime/scheduler/automation-run-completion.d.ts

@@ -0,0 +1,11 @@
+import type { SchedulerAutomationRun, SchedulerAutomationRunOutcome, SchedulerAutomationStartedRun } from "./contracts.js";
+import type { SchedulerContext } from "./service-context.js";
+export interface AutomationSchedulerRunCompletion {
+    runId: string;
+    automationId: string;
+    generation: number;
+    outcome: SchedulerAutomationRunOutcome;
+    finishedAt: string;
+}
+export declare function settleAutomationSchedulerRun(context: SchedulerContext, run: SchedulerAutomationRun, generation: number, execution: SchedulerAutomationStartedRun, release: () => void): Promise<void>;
+export declare function reconcileAutomationSchedulerCompletions(context: SchedulerContext): Promise<void>;

package/dist/src/runtime/scheduler/automation-run-completion.js

@@ -0,0 +1,93 @@
+import { isAutomationSchedulerRun } from "./scheduler-target.js";
+export async function settleAutomationSchedulerRun(context, run, generation, execution, release) {
+    const resourcesSettled = execution.resourcesSettled.catch((error) => {
+        try {
+            context.onError(error);
+        }
+        catch {
+            // A diagnostic callback cannot release admission before effects settle.
+        }
+    });
+    try {
+        const outcome = await execution.outcome.catch((error) => ({
+            status: "failed",
+            error: error instanceof Error ? error.message : String(error),
+        }));
+        const completion = {
+            runId: run.id,
+            automationId: run.target.automationId,
+            generation,
+            outcome,
+            finishedAt: new Date(context.now()).toISOString(),
+        };
+        await context.enqueue(async () => {
+            if (!canPersistAutomationCompletion(context, completion))
+                return;
+            context.pendingAutomationCompletions.set(run.id, completion);
+            await persistAutomationCompletion(context, completion);
+        });
+    }
+    catch (error) {
+        context.onError(error);
+    }
+    finally {
+        try {
+            await resourcesSettled;
+        }
+        finally {
+            release();
+        }
+    }
+}
+export async function reconcileAutomationSchedulerCompletions(context) {
+    for (const completion of context.pendingAutomationCompletions.values()) {
+        await persistAutomationCompletion(context, completion);
+    }
+}
+async function persistAutomationCompletion(context, completion) {
+    if (!canPersistAutomationCompletion(context, completion)) {
+        context.pendingAutomationCompletions.delete(completion.runId);
+        return;
+    }
+    const update = context.store.updateWithAutomations;
+    if (!update)
+        throw new Error("automation_store_unavailable");
+    try {
+        await update((scheduler, automations) => {
+            if (!canPersistAutomationCompletion(context, completion))
+                return;
+            const run = scheduler.runs.find((item) => item.id === completion.runId);
+            if (!isUnsettledAutomationRun(run, completion))
+                return;
+            if (!context.automationExecutor)
+                throw new Error("automation_executor_unavailable");
+            context.automationExecutor.settle(run, automations, completion.outcome);
+            const execution = automations.executions.find((item) => item.id === run.id);
+            const reportRef = completion.outcome.reportRef ?? execution?.reportRef;
+            if (!reportRef)
+                throw new Error("automation_report_missing");
+            run.status = completion.outcome.status;
+            run.finishedAt = completion.finishedAt;
+            run.reportRef = reportRef;
+            if (completion.outcome.error)
+                run.error = completion.outcome.error;
+        });
+        context.pendingAutomationCompletions.delete(completion.runId);
+    }
+    catch (error) {
+        // Only retry the terminal commit; never re-execute its effect.
+        context.onError(error);
+    }
+}
+function canPersistAutomationCompletion(context, completion) {
+    if (!context.running)
+        return false;
+    return context.generation === completion.generation;
+}
+function isUnsettledAutomationRun(run, completion) {
+    if (!run || !isAutomationSchedulerRun(run))
+        return false;
+    if (run.target.automationId !== completion.automationId)
+        return false;
+    return run.status === "running" || run.status === "stopping";
+}

package/dist/src/runtime/scheduler/automation-run-control.d.ts

@@ -0,0 +1,3 @@
+import type { SchedulerAutomationRun } from "./contracts.js";
+import { type SchedulerContext } from "./service-context.js";
+export declare function stopAutomationSchedulerRun(context: SchedulerContext, runId: string): Promise<SchedulerAutomationRun>;

package/dist/src/runtime/scheduler/automation-run-control.js

@@ -0,0 +1,48 @@
+import { requireCommittedAutomationExecution } from "./automation-job-management.js";
+import { requireRunningScheduler } from "./service-context.js";
+import { isAutomationSchedulerRun } from "./scheduler-target.js";
+export function stopAutomationSchedulerRun(context, runId) {
+    return context.enqueue(async () => {
+        requireRunningScheduler(context);
+        const update = context.store.updateWithAutomations;
+        const executor = context.automationExecutor;
+        if (!update || !executor)
+            throw new Error("automation_executor_unavailable");
+        let signalStop = false;
+        const run = await update((scheduler, automations) => {
+            const candidate = scheduler.runs.find((item) => item.id === runId);
+            if (!candidate || !isAutomationSchedulerRun(candidate))
+                throw new Error("automation_run_not_found");
+            if (candidate.status === "pending") {
+                executor.cancelPending(candidate, automations, "stopped");
+                const execution = requireCommittedAutomationExecution(automations, runId);
+                if (!execution.reportRef)
+                    throw new Error("automation_report_missing");
+                candidate.status = "cancelled";
+                candidate.reportRef = execution.reportRef;
+                candidate.finishedAt = new Date(context.now()).toISOString();
+                return candidate;
+            }
+            if (candidate.status === "running") {
+                const at = new Date(context.now()).toISOString();
+                const execution = requireCommittedAutomationExecution(automations, runId);
+                replaceExecution(automations.executions, execution, { ...execution, revision: execution.revision + 1, stopRequestedAt: at });
+                candidate.status = "stopping";
+                signalStop = true;
+                return candidate;
+            }
+            if (candidate.status === "stopping")
+                signalStop = true;
+            return candidate;
+        });
+        if (signalStop)
+            executor.stop(runId);
+        return run;
+    });
+}
+function replaceExecution(executions, existing, updated) {
+    const index = executions.findIndex((item) => item.id === existing.id);
+    if (index < 0)
+        throw new Error("automation_execution_checkpoint_missing");
+    executions[index] = updated;
+}

package/dist/src/runtime/scheduler/automation-run-records.d.ts

@@ -0,0 +1,5 @@
+import type { SchedulerAutomationJob, SchedulerAutomationRun, SchedulerSnapshot } from "./contracts.js";
+export declare function makeAutomationSchedulerRun(job: SchedulerAutomationJob, id: string, scheduledAt: string, trigger: SchedulerAutomationRun["trigger"], idempotencyKey?: string, admittedAt?: string): SchedulerAutomationRun;
+export declare function findPendingAutomationRun(state: SchedulerSnapshot, jobId: string): SchedulerAutomationRun | undefined;
+export declare function hasActiveAutomationRun(state: SchedulerSnapshot, automationId: string): boolean;
+export declare function requireAutomationSchedulerJob(state: SchedulerSnapshot, jobId: string): SchedulerAutomationJob;