@abot-ai/runtime 1.1.0 → 1.3.0

package/dist/src/runtime/scheduler/scheduler-engine.js

@@ -0,0 +1,174 @@
+import { nextSchedulerOccurrence } from "./next-occurrence.js";
+import { reconcileSchedulerCompletions, settleSchedulerRun, } from "./run-completion.js";
+import { findPendingRun, hasRunningSession, makeSchedulerRun, } from "./run-records.js";
+import { canBeginSchedulerRun, jobEpoch, } from "./service-context.js";
+export async function tickScheduler(context) {
+    if (!context.running)
+        return;
+    await reconcileSchedulerCompletions(context);
+    if (!context.running)
+        return;
+    const now = context.now();
+    const snapshot = await context.store.read();
+    const hasDue = snapshot.jobs.some((job) => isDueJob(job, now));
+    if (hasDue)
+        await enqueueDueOccurrences(context, now);
+    const pending = (await context.store.read()).runs.filter((run) => run.status === "pending");
+    for (const run of pending) {
+        if (!context.running)
+            return;
+        await dispatchPendingRun(context, run);
+    }
+}
+function isDueJob(job, now) {
+    if (job.state !== "active")
+        return false;
+    if (!job.nextRunAt)
+        return false;
+    return Date.parse(job.nextRunAt) <= now;
+}
+async function enqueueDueOccurrences(context, now) {
+    await context.store.update((state) => {
+        for (const job of state.jobs) {
+            if (!isDueJob(job, now))
+                continue;
+            const pending = findPendingRun(state, job.id);
+            if (!canRecordScheduledOccurrence(pending))
+                continue;
+            if (!pending) {
+                state.runs.push(makeSchedulerRun(job, job.nextRunAt, "schedule"));
+            }
+            job.nextRunAt = nextSchedulerOccurrence(job.schedule, job.timeZone, now);
+            if (!job.nextRunAt)
+                job.state = "completed";
+        }
+    });
+}
+function canRecordScheduledOccurrence(pending) {
+    if (!pending)
+        return true;
+    // A manual run cannot consume a recurrence. Keep its due time until the
+    // single pending slot can represent scheduled work instead.
+    return pending.trigger === "schedule";
+}
+async function dispatchPendingRun(context, pending) {
+    const epoch = jobEpoch(context, pending.jobId);
+    const exists = await lookupPendingRunSession(context, pending);
+    if (exists === undefined)
+        return;
+    if (!exists) {
+        context.deletedSessions.add(pending.sessionId);
+        await removeDeletedSession(context, pending.sessionId);
+        return;
+    }
+    if (!canBeginSchedulerRun(context, pending.jobId, pending.sessionId, epoch))
+        return;
+    const release = context.executor.tryReserve(pending.sessionId);
+    if (!release)
+        return;
+    let delegated = false;
+    try {
+        const claimed = await claimPendingRun(context, pending, epoch);
+        if (!claimed)
+            return;
+        // Last validity guard and start invocation are in the same synchronous turn.
+        if (!canBeginSchedulerRun(context, pending.jobId, pending.sessionId, epoch)) {
+            await cancelClaimedRun(context, pending.id);
+            return;
+        }
+        const execution = startCapturedRun(context, claimed.job, claimed.run);
+        delegated = true;
+        void settleSchedulerRun(context, claimed.run, context.generation, execution, release);
+    }
+    finally {
+        if (!delegated)
+            release();
+    }
+}
+async function lookupPendingRunSession(context, pending) {
+    const generation = context.generation;
+    try {
+        return await context.executor.sessionExists(pending.sessionId);
+    }
+    catch (cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        const error = new Error(`scheduler_session_lookup_failed: ${detail}`, {
+            cause,
+        });
+        // Settle after mutations already queued during lookup. A no-op edit changes
+        // the preparation epoch but must not cause this same failed run to retry.
+        // Cancellation or a replacement snapshot still wins by exact run identity.
+        void context
+            .enqueue(async () => {
+            if (!context.running)
+                return;
+            if (context.generation !== generation)
+                return;
+            await context.store.update((state) => {
+                const run = state.runs.find((candidate) => candidate.id === pending.id);
+                if (!run || run.status !== "pending")
+                    return;
+                run.status = "failed";
+                run.finishedAt = new Date(context.now()).toISOString();
+                run.error = error.message;
+            });
+        })
+            .catch(context.onError);
+        context.onError(error);
+        return undefined;
+    }
+}
+async function claimPendingRun(context, pending, epoch) {
+    return context.store.update((state) => {
+        if (!canBeginSchedulerRun(context, pending.jobId, pending.sessionId, epoch))
+            return null;
+        const job = state.jobs.find((item) => item.id === pending.jobId);
+        if (!job)
+            return null;
+        if (job.state === "cancelled")
+            return null;
+        const run = state.runs.find((item) => item.id === pending.id);
+        if (!run || run.status !== "pending")
+            return null;
+        if (job.state === "paused" && run.trigger !== "manual")
+            return null;
+        if (hasRunningSession(state, run.sessionId))
+            return null;
+        run.status = "running";
+        run.startedAt = new Date(context.now()).toISOString();
+        return { job, run };
+    });
+}
+function startCapturedRun(context, job, run) {
+    try {
+        // The immutable run text owns this invocation even after a later Job edit.
+        return context.executor.start({
+            ...job,
+            prompt: run.prompt,
+            title: run.title,
+            modelProfileId: run.modelProfileId,
+            agentMode: run.agentMode,
+            timeZone: run.timeZone,
+            revision: run.jobRevision,
+        }, run);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+}
+async function cancelClaimedRun(context, runId) {
+    await context.store.update((state) => {
+        const run = state.runs.find((candidate) => candidate.id === runId);
+        if (!run)
+            return;
+        run.status = "cancelled";
+        run.finishedAt = new Date(context.now()).toISOString();
+        delete run.startedAt;
+    });
+}
+async function removeDeletedSession(context, sessionId) {
+    await context.store.update((state) => {
+        state.jobs = state.jobs.filter((job) => job.sessionId !== sessionId);
+        state.runs = state.runs.filter((run) => run.sessionId !== sessionId);
+    });
+}

package/dist/src/runtime/scheduler/scheduler-service.d.ts

@@ -0,0 +1,10 @@
+import type { SchedulerExecutor, SchedulerService, SchedulerStore } from "./contracts.js";
+export interface SchedulerServiceOptions {
+    environmentId: string;
+    store: SchedulerStore;
+    executor: SchedulerExecutor;
+    now?: () => number;
+    tickIntervalMs?: number;
+    onError?: (error: unknown) => void;
+}
+export declare function createSchedulerService(options: SchedulerServiceOptions): SchedulerService;

package/dist/src/runtime/scheduler/scheduler-service.js

@@ -0,0 +1,115 @@
+import { changeSchedulerJobState, createSchedulerJob, deleteSchedulerSession, matchesSchedulerFilter, requestSchedulerRunNow, updateSchedulerJob, } from "./job-management.js";
+import { tickScheduler } from "./scheduler-engine.js";
+import { requireRunningScheduler, } from "./service-context.js";
+import { recoverSchedulerSnapshot } from "./startup-recovery.js";
+import { querySchedulerRuns } from "./run-list-query.js";
+import { createSchedulerWorkingStore } from "./working-store.js";
+import { SchedulerSessionDeletionState } from "./session-deletion-state.js";
+export function createSchedulerService(options) {
+    let tail = Promise.resolve();
+    let releaseOwner;
+    let timer;
+    let ticking;
+    const context = {
+        environmentId: options.environmentId,
+        store: createSchedulerWorkingStore(options.store),
+        executor: options.executor,
+        now: options.now ?? Date.now,
+        running: false,
+        generation: 0,
+        jobEpochs: new Map(),
+        pendingJobMutations: new Set(),
+        deletedSessions: new SchedulerSessionDeletionState(),
+        pendingCompletions: new Map(),
+        enqueue: (operation) => {
+            const result = tail.then(operation);
+            tail = result.catch(() => undefined);
+            return result;
+        },
+        onError: options.onError ?? ((error) => console.error("Scheduler failed:", error)),
+    };
+    const service = {
+        start: () => {
+            const requestedGeneration = context.generation;
+            return context.enqueue(async () => {
+                if (requestedGeneration !== context.generation)
+                    return;
+                if (context.running)
+                    return;
+                const release = await options.store.acquire();
+                releaseOwner = release;
+                try {
+                    await context.store.update((state) => {
+                        recoverSchedulerSnapshot(state, options.environmentId, context.now());
+                    });
+                    if (requestedGeneration !== context.generation) {
+                        await release();
+                        releaseOwner = undefined;
+                        return;
+                    }
+                    context.running = true;
+                    timer = setInterval(() => {
+                        void service.tick().catch(context.onError);
+                    }, options.tickIntervalMs ?? 1_000);
+                    timer.unref();
+                }
+                catch (error) {
+                    await release();
+                    releaseOwner = undefined;
+                    throw error;
+                }
+            });
+        },
+        stop: () => {
+            // Stop invalidates every in-flight preparation before waiting for disk writes.
+            context.generation += 1;
+            context.running = false;
+            context.pendingCompletions.clear();
+            if (timer)
+                clearInterval(timer);
+            timer = undefined;
+            return context.enqueue(async () => {
+                const release = releaseOwner;
+                releaseOwner = undefined;
+                await release?.();
+            });
+        },
+        tick: () => {
+            if (ticking)
+                return ticking;
+            const pending = context.enqueue(() => tickScheduler(context));
+            ticking = pending;
+            void pending
+                .finally(() => {
+                if (ticking === pending)
+                    ticking = undefined;
+            })
+                .catch(() => undefined);
+            return pending;
+        },
+        create: (input) => createSchedulerJob(context, input),
+        list: (filter = {}) => context.enqueue(async () => {
+            requireRunningScheduler(context);
+            return (await context.store.read()).jobs.filter((job) => matchesSchedulerFilter(job, filter));
+        }),
+        get: (jobId) => context.enqueue(async () => {
+            requireRunningScheduler(context);
+            return ((await context.store.read()).jobs.find((job) => job.id === jobId) ??
+                null);
+        }),
+        update: (jobId, patch) => updateSchedulerJob(context, jobId, patch),
+        pause: (jobId) => changeSchedulerJobState(context, jobId, "paused"),
+        resume: (jobId) => changeSchedulerJobState(context, jobId, "active"),
+        cancel: (jobId) => changeSchedulerJobState(context, jobId, "cancelled"),
+        runNow: (jobId) => requestSchedulerRunNow(context, jobId),
+        deleteSession: (sessionId) => deleteSchedulerSession(context, sessionId),
+        listRuns: (jobId, query) => context.enqueue(async () => {
+            requireRunningScheduler(context);
+            if (options.store.readRuns)
+                return options.store.readRuns(jobId, query);
+            const runs = (await options.store.read()).runs;
+            return querySchedulerRuns(runs, jobId, query);
+        }),
+    };
+    return service;
+}

package/dist/src/runtime/scheduler/service-context.d.ts

@@ -0,0 +1,21 @@
+import type { SchedulerExecutor, SchedulerStore } from "./contracts.js";
+import type { SchedulerRunCompletion } from "./run-completion.js";
+import type { SchedulerSessionDeletionState } from "./session-deletion-state.js";
+export interface SchedulerContext {
+    environmentId: string;
+    store: SchedulerStore;
+    executor: SchedulerExecutor;
+    now(): number;
+    running: boolean;
+    generation: number;
+    jobEpochs: Map<string, number>;
+    pendingJobMutations: Set<string>;
+    deletedSessions: SchedulerSessionDeletionState;
+    pendingCompletions: Map<string, SchedulerRunCompletion>;
+    enqueue<T>(operation: () => Promise<T>): Promise<T>;
+    onError(error: unknown): void;
+}
+export declare function requireRunningScheduler(context: SchedulerContext): void;
+export declare function jobEpoch(context: SchedulerContext, jobId: string): number;
+export declare function invalidateJob(context: SchedulerContext, jobId: string): () => void;
+export declare function canBeginSchedulerRun(context: SchedulerContext, jobId: string, sessionId: string, epoch: number): boolean;

package/dist/src/runtime/scheduler/service-context.js

@@ -0,0 +1,26 @@
+export function requireRunningScheduler(context) {
+    if (!context.running)
+        throw new Error("scheduler_not_started");
+}
+export function jobEpoch(context, jobId) {
+    return context.jobEpochs.get(jobId) ?? 0;
+}
+export function invalidateJob(context, jobId) {
+    const epoch = jobEpoch(context, jobId) + 1;
+    context.jobEpochs.set(jobId, epoch);
+    context.pendingJobMutations.add(jobId);
+    return () => {
+        if (jobEpoch(context, jobId) !== epoch)
+            return;
+        context.pendingJobMutations.delete(jobId);
+    };
+}
+export function canBeginSchedulerRun(context, jobId, sessionId, epoch) {
+    if (!context.running)
+        return false;
+    if (context.deletedSessions.has(sessionId))
+        return false;
+    if (context.pendingJobMutations.has(jobId))
+        return false;
+    return jobEpoch(context, jobId) === epoch;
+}

package/dist/src/runtime/scheduler/session-deletion-state.d.ts

@@ -0,0 +1,9 @@
+/** Accepted deletion survives storage failure; rejected lifecycle calls release intent. */
+export declare class SchedulerSessionDeletionState {
+    private readonly confirmed;
+    private readonly pending;
+    has(sessionId: string): boolean;
+    add(sessionId: string): void;
+    reserveIntent(sessionId: string): () => void;
+    private canReleaseSessionIntents;
+}

package/dist/src/runtime/scheduler/session-deletion-state.js

@@ -0,0 +1,30 @@
+/** Accepted deletion survives storage failure; rejected lifecycle calls release intent. */
+export class SchedulerSessionDeletionState {
+    confirmed = new Set();
+    pending = new Map();
+    has(sessionId) {
+        if (this.confirmed.has(sessionId))
+            return true;
+        return this.pending.has(sessionId);
+    }
+    add(sessionId) {
+        this.confirmed.add(sessionId);
+    }
+    reserveIntent(sessionId) {
+        const reservations = this.pending.get(sessionId) ?? new Set();
+        const intent = Symbol();
+        reservations.add(intent);
+        this.pending.set(sessionId, reservations);
+        return () => {
+            reservations.delete(intent);
+            if (!this.canReleaseSessionIntents(sessionId, reservations))
+                return;
+            this.pending.delete(sessionId);
+        };
+    }
+    canReleaseSessionIntents(sessionId, reservations) {
+        if (reservations.size > 0)
+            return false;
+        return this.pending.get(sessionId) === reservations;
+    }
+}

package/dist/src/runtime/scheduler/snapshot-validation.d.ts

@@ -0,0 +1,4 @@
+import type { SchedulerJob, SchedulerRun, SchedulerSnapshot } from "./contracts.js";
+export declare function parseStoredJob(value: unknown): SchedulerJob;
+export declare function parseStoredRun(value: unknown): SchedulerRun;
+export declare function parseSchedulerSnapshot(value: unknown): SchedulerSnapshot;

package/dist/src/runtime/scheduler/snapshot-validation.js

@@ -0,0 +1,112 @@
+import { normalizeStoredSchedulerSchedule, validateSchedulerJobInput, validateTimeZone, } from "./schedule-validation.js";
+function isRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    return !Array.isArray(value);
+}
+function failSnapshot() {
+    throw new Error("scheduler_store_corrupt");
+}
+function requireSnapshotInstant(value) {
+    if (typeof value !== "string")
+        failSnapshot();
+    if (!Number.isFinite(Date.parse(value)))
+        failSnapshot();
+}
+export function parseStoredJob(value) {
+    if (!isRecord(value))
+        failSnapshot();
+    const job = value;
+    validateSchedulerJobInput(job);
+    if (!job.id || !job.environmentId)
+        failSnapshot();
+    if (job.toolPermissionMode !== "full_access")
+        failSnapshot();
+    if (!["active", "paused", "cancelled", "completed"].includes(job.state))
+        failSnapshot();
+    if (!Number.isSafeInteger(job.revision))
+        failSnapshot();
+    requireSnapshotInstant(job.createdAt);
+    requireSnapshotInstant(job.updatedAt);
+    if (job.nextRunAt !== null)
+        requireSnapshotInstant(job.nextRunAt);
+    // Canonical storage must not silently synthesize a missing timer/interval anchor.
+    if (job.schedule?.kind === "timer" && !job.schedule.at)
+        failSnapshot();
+    if (job.schedule?.kind === "interval" && !job.schedule.anchorAt)
+        failSnapshot();
+    const normalized = normalizeStoredSchedulerSchedule(job.schedule);
+    return { ...job, schedule: normalized };
+}
+export function parseStoredRun(value) {
+    if (!isRecord(value))
+        failSnapshot();
+    for (const field of [
+        "id",
+        "jobId",
+        "environmentId",
+        "sessionId",
+        "requestId",
+        "title",
+        "prompt",
+        "modelProfileId",
+        "timeZone",
+    ]) {
+        if (typeof value[field] !== "string")
+            failSnapshot();
+    }
+    if (!["fast", "reasoning", "deep"].includes(String(value.agentMode)))
+        failSnapshot();
+    if (!Number.isSafeInteger(value.jobRevision))
+        failSnapshot();
+    if (Number(value.jobRevision) < 1)
+        failSnapshot();
+    validateTimeZone(String(value.timeZone));
+    const states = [
+        "pending",
+        "running",
+        "succeeded",
+        "failed",
+        "cancelled",
+        "interrupted",
+        "missed",
+    ];
+    if (!states.includes(String(value.status)))
+        failSnapshot();
+    if (!["schedule", "manual"].includes(String(value.trigger)))
+        failSnapshot();
+    requireSnapshotInstant(value.scheduledAt);
+    if (value.startedAt !== undefined)
+        requireSnapshotInstant(value.startedAt);
+    if (value.finishedAt !== undefined)
+        requireSnapshotInstant(value.finishedAt);
+    return value;
+}
+export function parseSchedulerSnapshot(value) {
+    if (!isRecord(value))
+        failSnapshot();
+    if (value.schemaVersion !== 1)
+        failSnapshot();
+    if (!Array.isArray(value.jobs))
+        failSnapshot();
+    if (!Array.isArray(value.runs))
+        failSnapshot();
+    const jobs = value.jobs.map(parseStoredJob);
+    const runs = value.runs.map(parseStoredRun);
+    if (new Set(jobs.map((job) => job.id)).size !== jobs.length)
+        failSnapshot();
+    if (new Set(runs.map((run) => run.id)).size !== runs.length)
+        failSnapshot();
+    for (const run of runs) {
+        const owner = jobs.find((job) => job.id === run.jobId);
+        if (!owner)
+            failSnapshot();
+        if (owner.sessionId !== run.sessionId)
+            failSnapshot();
+        if (owner.environmentId !== run.environmentId)
+            failSnapshot();
+        if (run.jobRevision > owner.revision)
+            failSnapshot();
+    }
+    return { schemaVersion: 1, jobs, runs };
+}

package/dist/src/runtime/scheduler/startup-recovery.d.ts

@@ -0,0 +1,2 @@
+import type { SchedulerSnapshot } from "./contracts.js";
+export declare function recoverSchedulerSnapshot(state: SchedulerSnapshot, environmentId: string, now: number): void;

package/dist/src/runtime/scheduler/startup-recovery.js

@@ -0,0 +1,38 @@
+import { nextSchedulerOccurrence } from "./next-occurrence.js";
+import { makeSchedulerRun } from "./run-records.js";
+export function recoverSchedulerSnapshot(state, environmentId, now) {
+    const at = new Date(now).toISOString();
+    for (const job of state.jobs) {
+        if (job.environmentId !== environmentId)
+            throw new Error("scheduler_environment_mismatch");
+    }
+    for (const run of state.runs) {
+        if (run.status === "running") {
+            run.status = "interrupted";
+            run.finishedAt = at;
+            run.error = "scheduler_process_stopped";
+            continue;
+        }
+        if (run.status !== "pending")
+            continue;
+        run.status = "missed";
+        run.finishedAt = at;
+        run.error = "scheduler_offline_no_catchup";
+    }
+    for (const job of state.jobs) {
+        if (job.state !== "active")
+            continue;
+        if (!job.nextRunAt)
+            continue;
+        if (Date.parse(job.nextRunAt) > now)
+            continue;
+        const missed = makeSchedulerRun(job, job.nextRunAt, "schedule");
+        missed.status = "missed";
+        missed.finishedAt = at;
+        missed.error = "scheduler_offline_no_catchup";
+        state.runs.push(missed);
+        job.nextRunAt = nextSchedulerOccurrence(job.schedule, job.timeZone, now);
+        if (!job.nextRunAt)
+            job.state = "completed";
+    }
+}

package/dist/src/runtime/scheduler/validation-error.d.ts

@@ -0,0 +1,4 @@
+export declare class SchedulerValidationError extends Error {
+    readonly code: string;
+    constructor(code: string, detail: string);
+}

package/dist/src/runtime/scheduler/validation-error.js

@@ -0,0 +1,8 @@
+export class SchedulerValidationError extends Error {
+    code;
+    constructor(code, detail) {
+        super(`${code}: ${detail}`);
+        this.code = code;
+        this.name = "SchedulerValidationError";
+    }
+}

package/dist/src/runtime/scheduler/working-store.d.ts

@@ -0,0 +1,3 @@
+import type { SchedulerStore } from "./contracts.js";
+/** Older injected stores may ignore the view and still satisfy the full contract. */
+export declare function createSchedulerWorkingStore(store: SchedulerStore): SchedulerStore;

package/dist/src/runtime/scheduler/working-store.js

@@ -0,0 +1,8 @@
+/** Older injected stores may ignore the view and still satisfy the full contract. */
+export function createSchedulerWorkingStore(store) {
+    return {
+        acquire: () => store.acquire(),
+        read: () => store.read("active"),
+        update: (mutate) => store.update(mutate, "active"),
+    };
+}

package/dist/src/runtime/session/request-session.d.ts

@@ -25,6 +25,7 @@ export declare function initializeRequestSession(params: {
     sessionStore: RequestSessionStore;
     attachmentStore?: RuntimeAttachmentStore;
     events: EventSink;
+    schedule?: import("../../sessions/schedule-metadata.js").ScheduleMessageReference;
 }): Promise<Readonly<{
     prompt: string;
     modelAttachments: ModelGatewayAttachment[];

package/dist/src/runtime/session/request-session.js

@@ -15,13 +15,26 @@ export async function openRequestSession(params) {
 }
 export async function initializeRequestSession(params) {
     params.events.event("thinking.started");
-    await params.sessionStore.appendMessage(params.sessionId, "user", params.prompt, {
+    const persisted = await params.sessionStore.appendMessage(params.sessionId, "user", params.prompt, {
         lastAgentMode: params.agentMode,
         requestId: params.requestId,
+        ...(params.schedule
+            ? { source: "cron", schedule: params.schedule }
+            : {}),
         ...(params.opened.attachments.length > 0
             ? { attachments: params.opened.attachments }
             : {}),
     });
+    if (params.schedule) {
+        const message = persisted.messages.find((entry) => entry.requestId === params.requestId && entry.role === "user");
+        params.events.event("schedule.triggered", {
+            sessionId: params.sessionId,
+            schedule: params.schedule,
+            messageId: message?.id,
+            text: params.prompt,
+            createdAt: message?.createdAt,
+        });
+    }
     const [modelAttachments, toolAttachments] = await Promise.all([
         resolveModelGatewayAttachments({
             attachments: params.opened.attachments,

package/dist/src/runtime/session/session-attachment-deletion.d.ts

@@ -0,0 +1,8 @@
+import type { RuntimeAttachmentStore } from "../attachments/store.js";
+import type { SessionStore } from "../ports.js";
+type DeletionStore = Pick<SessionStore, "deleteSessionWithStats">;
+/** The composed owner already finalizes attachments within its session transaction. */
+export declare function bindManagedSessionAttachmentDeletion(sessions: DeletionStore, attachments: RuntimeAttachmentStore): void;
+export declare function deleteSessionWithAttachments(sessions: DeletionStore, attachments: RuntimeAttachmentStore | undefined, sessionId: string): Promise<import("../../sessions/types.js").SessionDeleteResult>;
+export declare function deleteSessionAttachmentsIfSupported(attachments: RuntimeAttachmentStore | undefined, sessionId: string): Promise<void>;
+export {};