@abot-ai/runtime 1.1.0 → 1.3.0

package/dist/src/runtime/scheduler/journal-transaction.js

@@ -0,0 +1,104 @@
+import { parseStoredJob, parseStoredRun } from "./snapshot-validation.js";
+export function parseSchedulerTransaction(value) {
+    if (!isSchedulerTransactionRecord(value))
+        throw new Error("scheduler_store_corrupt");
+    const raw = value;
+    if (!hasSchedulerTransactionCollections(raw))
+        throw new Error("scheduler_store_corrupt");
+    const transaction = {
+        version: 1,
+        jobs: raw.jobs.map(parseStoredJob),
+        runs: raw.runs.map(parseStoredRun),
+        deletedJobs: requireJournalIds(raw.deletedJobs),
+        deletedRuns: requireJournalIds(raw.deletedRuns),
+        ...(raw.jobOrder === undefined
+            ? {}
+            : { jobOrder: requireJournalIds(raw.jobOrder) }),
+        ...(raw.runOrder === undefined
+            ? {}
+            : { runOrder: requireJournalIds(raw.runOrder) }),
+    };
+    assertJournalTransactionIds(transaction);
+    return transaction;
+}
+function isSchedulerTransactionRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    return !Array.isArray(value);
+}
+function hasSchedulerTransactionCollections(value) {
+    if (value.version !== 1)
+        return false;
+    if (!Array.isArray(value.jobs))
+        return false;
+    return Array.isArray(value.runs);
+}
+export function assertJournalTransactionIds(transaction) {
+    assertDisjointJournalRecords(transaction.jobs, transaction.deletedJobs);
+    assertDisjointJournalRecords(transaction.runs, transaction.deletedRuns);
+    if (transaction.jobOrder)
+        requireJournalIds(transaction.jobOrder);
+    if (transaction.runOrder)
+        requireJournalIds(transaction.runOrder);
+}
+function assertDisjointJournalRecords(records, deleted) {
+    const ids = new Set(requireJournalIds(records.map((record) => record.id)));
+    if (hasOverlappingJournalIds(ids, requireJournalIds(deleted)))
+        throw new Error("scheduler_store_corrupt");
+}
+function hasOverlappingJournalIds(upserted, deleted) {
+    return deleted.some((id) => upserted.has(id));
+}
+function requireJournalIds(value) {
+    if (!Array.isArray(value))
+        throw new Error("scheduler_store_corrupt");
+    if (!hasOnlyJournalIdStrings(value))
+        throw new Error("scheduler_store_corrupt");
+    if (hasDuplicateJournalIds(value))
+        throw new Error("scheduler_store_corrupt");
+    return [...value];
+}
+function hasOnlyJournalIdStrings(value) {
+    return value.every((id) => typeof id === "string");
+}
+function hasDuplicateJournalIds(value) {
+    return new Set(value).size !== value.length;
+}
+function changedRecords(before, after) {
+    const originals = new Map(before.map((item) => [item.id, item]));
+    return after.filter((item) => JSON.stringify(originals.get(item.id)) !== JSON.stringify(item));
+}
+function removedRecords(before, after) {
+    const retained = new Set(after.map((item) => item.id));
+    return before.filter((item) => !retained.has(item.id)).map((item) => item.id);
+}
+export function schedulerTransaction(before, after, view) {
+    const jobOrder = after.jobs.map((item) => item.id);
+    const runOrder = after.runs.map((item) => item.id);
+    return {
+        version: 1,
+        jobs: changedRecords(before.jobs, after.jobs),
+        runs: changedRecords(before.runs, after.runs),
+        deletedJobs: removedRecords(before.jobs, after.jobs),
+        deletedRuns: removedRecords(before.runs, after.runs),
+        ...(hasJournalOrderChanged(before.jobs, jobOrder) ? { jobOrder } : {}),
+        ...(shouldPersistRunOrder(view, before.runs, runOrder) ? { runOrder } : {}),
+    };
+}
+function hasJournalOrderChanged(before, order) {
+    if (before.length !== order.length)
+        return true;
+    return before.some((record, index) => record.id !== order[index]);
+}
+function shouldPersistRunOrder(view, before, order) {
+    if (view === "active")
+        return false;
+    return hasJournalOrderChanged(before, order);
+}
+export function hasSchedulerTransactionChanges(value) {
+    if (value.jobs.length || value.runs.length)
+        return true;
+    if (value.deletedJobs.length || value.deletedRuns.length)
+        return true;
+    return value.jobOrder !== undefined || value.runOrder !== undefined;
+}

package/dist/src/runtime/scheduler/next-occurrence.d.ts

@@ -0,0 +1,3 @@
+import type { SchedulerSchedule } from "./contracts.js";
+/** Strictly after the supplied instant. Never shifts missing calendar dates or times. */
+export declare function nextSchedulerOccurrence(schedule: SchedulerSchedule, timeZone: string, after: number): string | null;

package/dist/src/runtime/scheduler/next-occurrence.js

@@ -0,0 +1,39 @@
+import { isSupportedSchedulerInstant, schedulerInstantFromMilliseconds, } from "./instant-validation.js";
+import { nextIntervalOccurrence } from "./interval-range.js";
+import { addCalendarDays, calendarDateAt, calendarWeekday, resolveCalendarTime, } from "./calendar-time.js";
+/** Strictly after the supplied instant. Never shifts missing calendar dates or times. */
+export function nextSchedulerOccurrence(schedule, timeZone, after) {
+    switch (schedule.kind) {
+        case "timer":
+        case "once":
+            return Date.parse(schedule.at) > after ? schedule.at : null;
+        case "interval":
+            return nextIntervalOccurrence(schedule, after);
+        default:
+            return nextCalendarOccurrence(schedule, timeZone, after);
+    }
+}
+function nextCalendarOccurrence(schedule, timeZone, after) {
+    const start = calendarDateAt(after, timeZone);
+    for (let offset = 0; offset < 370; offset += 1) {
+        const date = addCalendarDays(start, offset);
+        if (!matchesCalendarDay(schedule, date))
+            continue;
+        const instant = resolveCalendarTime(date, schedule.at, timeZone);
+        if (instant === null)
+            continue;
+        if (instant <= after)
+            continue;
+        if (!isSupportedSchedulerInstant(instant))
+            return null;
+        return schedulerInstantFromMilliseconds(instant);
+    }
+    throw new Error("scheduler_next_occurrence_unavailable");
+}
+function matchesCalendarDay(schedule, date) {
+    if (schedule.kind === "daily")
+        return true;
+    if (schedule.kind === "monthly")
+        return date.day === schedule.dayOfMonth;
+    return schedule.weekdays.includes(calendarWeekday(date));
+}

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

@@ -0,0 +1,12 @@
+import type { SchedulerRun, SchedulerRunOutcome } from "./contracts.js";
+import type { SchedulerContext } from "./service-context.js";
+export interface SchedulerRunCompletion {
+    runId: string;
+    sessionId: string;
+    requestId: string;
+    generation: number;
+    outcome: SchedulerRunOutcome;
+    finishedAt: string;
+}
+export declare function settleSchedulerRun(context: SchedulerContext, run: SchedulerRun, generation: number, execution: Promise<SchedulerRunOutcome>, release: () => void): Promise<void>;
+export declare function reconcileSchedulerCompletions(context: SchedulerContext): Promise<void>;

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

@@ -0,0 +1,77 @@
+export async function settleSchedulerRun(context, run, generation, execution, release) {
+    const identity = {
+        runId: run.id,
+        sessionId: run.sessionId,
+        requestId: run.requestId,
+    };
+    try {
+        const outcome = await execution.catch((error) => ({
+            status: "failed",
+            error: error instanceof Error ? error.message : String(error),
+        }));
+        const completion = {
+            ...identity,
+            generation,
+            outcome: { ...outcome },
+            finishedAt: new Date(context.now()).toISOString(),
+        };
+        await context.enqueue(async () => {
+            if (!canPersistCompletion(context, completion))
+                return;
+            context.pendingCompletions.set(completion.runId, completion);
+            await persistCompletion(context, completion);
+        });
+    }
+    catch (error) {
+        context.onError(error);
+    }
+    finally {
+        release();
+    }
+}
+export async function reconcileSchedulerCompletions(context) {
+    // Each ordinary tick attempts retained writes once, without executing work.
+    for (const completion of context.pendingCompletions.values()) {
+        await persistCompletion(context, completion);
+    }
+}
+async function persistCompletion(context, completion) {
+    if (!canPersistCompletion(context, completion)) {
+        context.pendingCompletions.delete(completion.runId);
+        return;
+    }
+    try {
+        await context.store.update((state) => {
+            // Stop and session deletion can arrive while the store awaits its read.
+            if (!canPersistCompletion(context, completion))
+                return;
+            const run = state.runs.find((candidate) => candidate.id === completion.runId);
+            if (!isUnsettledCapturedRun(run, completion))
+                return;
+            Object.assign(run, completion.outcome, {
+                finishedAt: completion.finishedAt,
+            });
+        });
+        context.pendingCompletions.delete(completion.runId);
+    }
+    catch (error) {
+        // Keep the captured outcome for a later clock tick, not an execution retry.
+        context.onError(error);
+    }
+}
+function canPersistCompletion(context, completion) {
+    if (!context.running)
+        return false;
+    if (context.generation !== completion.generation)
+        return false;
+    return !context.deletedSessions.has(completion.sessionId);
+}
+function isUnsettledCapturedRun(run, completion) {
+    if (!run)
+        return false;
+    if (run.status !== "running")
+        return false;
+    if (run.sessionId !== completion.sessionId)
+        return false;
+    return run.requestId === completion.requestId;
+}

package/dist/src/runtime/scheduler/run-list-query.d.ts

@@ -0,0 +1,5 @@
+import type { SchedulerRun, SchedulerRunListQuery } from "./contracts.js";
+/** Omitted queries retain the public service's complete, chronological result. */
+type RunListIdentity = Pick<SchedulerRun, "id" | "jobId" | "scheduledAt">;
+export declare function querySchedulerRuns<T extends RunListIdentity>(runs: readonly T[], jobId: string | undefined, query: SchedulerRunListQuery | undefined): T[];
+export {};

package/dist/src/runtime/scheduler/run-list-query.js

@@ -0,0 +1,38 @@
+export function querySchedulerRuns(runs, jobId, query) {
+    const scoped = runs.filter((run) => jobId === undefined || run.jobId === jobId);
+    if (query === undefined)
+        return scoped;
+    const limit = requireRunPageLimit(query?.limit);
+    const ordered = scoped.sort(compareNewestRuns);
+    const offset = runCursorOffset(ordered, query.cursor);
+    return ordered.slice(offset, offset + limit);
+}
+function requireRunPageLimit(limit) {
+    if (!Number.isSafeInteger(limit))
+        throw new Error("scheduler_run_page_limit_invalid");
+    if (Number(limit) < 1)
+        throw new Error("scheduler_run_page_limit_invalid");
+    if (Number(limit) > 101)
+        throw new Error("scheduler_run_page_limit_invalid");
+    return Number(limit);
+}
+function runCursorOffset(runs, cursor) {
+    if (cursor === undefined)
+        return 0;
+    if (typeof cursor !== "string")
+        throw new Error("scheduler_run_cursor_invalid");
+    if (!cursor)
+        throw new Error("scheduler_run_cursor_invalid");
+    const index = runs.findIndex((run) => run.id === cursor);
+    if (index < 0)
+        throw new Error("scheduler_run_cursor_not_found");
+    return index + 1;
+}
+function compareNewestRuns(left, right) {
+    const scheduled = Date.parse(right.scheduledAt) - Date.parse(left.scheduledAt);
+    if (scheduled !== 0)
+        return scheduled;
+    if (left.id === right.id)
+        return 0;
+    return left.id < right.id ? 1 : -1;
+}

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

@@ -0,0 +1,6 @@
+import type { SchedulerJob, SchedulerRun, SchedulerSnapshot } from "./contracts.js";
+export declare function makeSchedulerRun(job: SchedulerJob, scheduledAt: string, trigger: SchedulerRun["trigger"]): SchedulerRun;
+export declare function findPendingRun(state: SchedulerSnapshot, jobId: string): SchedulerRun | undefined;
+export declare function cancelPendingRuns(state: SchedulerSnapshot, jobId: string, at: string): void;
+export declare function requireSchedulerJob(state: SchedulerSnapshot, jobId: string): SchedulerJob;
+export declare function hasRunningSession(state: SchedulerSnapshot, sessionId: string): boolean;

package/dist/src/runtime/scheduler/run-records.js

@@ -0,0 +1,41 @@
+import { randomUUID } from "node:crypto";
+export function makeSchedulerRun(job, scheduledAt, trigger) {
+    return {
+        id: randomUUID(),
+        requestId: randomUUID(),
+        jobId: job.id,
+        environmentId: job.environmentId,
+        sessionId: job.sessionId,
+        title: job.title,
+        prompt: job.prompt,
+        modelProfileId: job.modelProfileId,
+        agentMode: job.agentMode,
+        timeZone: job.timeZone,
+        jobRevision: job.revision,
+        scheduledAt,
+        trigger,
+        status: "pending",
+    };
+}
+export function findPendingRun(state, jobId) {
+    return state.runs.find((run) => run.jobId === jobId && run.status === "pending");
+}
+export function cancelPendingRuns(state, jobId, at) {
+    for (const run of state.runs) {
+        if (run.jobId !== jobId)
+            continue;
+        if (run.status !== "pending")
+            continue;
+        run.status = "cancelled";
+        run.finishedAt = at;
+    }
+}
+export function requireSchedulerJob(state, jobId) {
+    const job = state.jobs.find((candidate) => candidate.id === jobId);
+    if (!job)
+        throw new Error("scheduler_job_not_found");
+    return job;
+}
+export function hasRunningSession(state, sessionId) {
+    return state.runs.some((run) => run.sessionId === sessionId && run.status === "running");
+}

package/dist/src/runtime/scheduler/schedule-update.d.ts

@@ -0,0 +1,3 @@
+import type { SchedulerSchedule, SchedulerScheduleInput } from "./contracts.js";
+/** PATCH preserves omitted or exact stored timing; actual edits are new input. */
+export declare function normalizeSchedulerScheduleUpdate(stored: SchedulerSchedule, input: SchedulerScheduleInput | undefined, now: number): SchedulerSchedule;

package/dist/src/runtime/scheduler/schedule-update.js

@@ -0,0 +1,22 @@
+import { normalizeSchedulerSchedule } from "./schedule-validation.js";
+/** PATCH preserves omitted or exact stored timing; actual edits are new input. */
+export function normalizeSchedulerScheduleUpdate(stored, input, now) {
+    if (input === undefined)
+        return stored;
+    if (isExactStoredTimerSchedule(stored, input))
+        return stored;
+    return normalizeSchedulerSchedule(input, now);
+}
+function isExactStoredTimerSchedule(stored, input) {
+    if (!input || typeof input !== "object")
+        return false;
+    if (stored.kind !== "timer")
+        return false;
+    if (input.kind !== "timer")
+        return false;
+    if (input.delayMs !== stored.delayMs)
+        return false;
+    if (!("at" in input))
+        return false;
+    return input.at === stored.at;
+}

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

@@ -0,0 +1,10 @@
+import type { CreateSchedulerJobInput, SchedulerSchedule, SchedulerScheduleInput } from "./contracts.js";
+export { SchedulerValidationError } from "./validation-error.js";
+export { parseSchedulerInstant } from "./instant-validation.js";
+export declare function requireSchedulerText(value: unknown, field: string): string;
+export declare function validateSchedulerJobInput(input: CreateSchedulerJobInput): void;
+export declare function validateTimeZone(timeZone: string): void;
+export declare function requireCalendarHour(value: unknown): string;
+export declare function normalizeSchedulerSchedule(input: SchedulerScheduleInput, now: number): SchedulerSchedule;
+/** Stored timer deadlines are canonical state, not new relative timer input. */
+export declare function normalizeStoredSchedulerSchedule(schedule: SchedulerSchedule): SchedulerSchedule;

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

@@ -0,0 +1,132 @@
+import { SchedulerValidationError } from "./validation-error.js";
+import { parseSchedulerInstant, schedulerInstantFromMilliseconds, } from "./instant-validation.js";
+export { SchedulerValidationError } from "./validation-error.js";
+export { parseSchedulerInstant } from "./instant-validation.js";
+export function requireSchedulerText(value, field) {
+    if (typeof value !== "string") {
+        throw new SchedulerValidationError("scheduler_invalid_job", `${field} must be text`);
+    }
+    const text = value.trim();
+    if (!text)
+        throw new SchedulerValidationError("scheduler_invalid_job", `${field} is required`);
+    return text;
+}
+export function validateSchedulerJobInput(input) {
+    if (!input || typeof input !== "object") {
+        throw new SchedulerValidationError("scheduler_invalid_job", "job input is required");
+    }
+    for (const field of [
+        "sessionId",
+        "title",
+        "prompt",
+        "modelProfileId",
+    ]) {
+        requireSchedulerText(input[field], field);
+    }
+    const allowedModes = ["fast", "reasoning", "deep"];
+    if (!allowedModes.includes(input.agentMode)) {
+        throw new SchedulerValidationError("scheduler_invalid_job", "agentMode is invalid");
+    }
+    validateTimeZone(input.timeZone);
+}
+export function validateTimeZone(timeZone) {
+    try {
+        requireSchedulerText(timeZone, "timeZone");
+        new Intl.DateTimeFormat("en", { timeZone }).format();
+    }
+    catch {
+        throw new SchedulerValidationError("scheduler_invalid_timezone", "An IANA timeZone is required");
+    }
+}
+function requirePositiveDuration(value) {
+    if (!Number.isSafeInteger(value)) {
+        throw new SchedulerValidationError("scheduler_invalid_schedule", "duration must be integer milliseconds");
+    }
+    if (value < 1_000) {
+        throw new SchedulerValidationError("scheduler_invalid_schedule", "duration must be at least one second");
+    }
+    return value;
+}
+export function requireCalendarHour(value) {
+    if (typeof value !== "string") {
+        throw new SchedulerValidationError("scheduler_exact_time_required", "Supply an exact HH:mm time");
+    }
+    if (!/^([01]\d|2[0-3]):[0-5]\d$/.test(value)) {
+        throw new SchedulerValidationError("scheduler_exact_time_required", "Supply an exact HH:mm time");
+    }
+    return value;
+}
+export function normalizeSchedulerSchedule(input, now) {
+    if (!input || typeof input !== "object") {
+        throw new SchedulerValidationError("scheduler_invalid_schedule", "schedule is required");
+    }
+    switch (input.kind) {
+        case "timer": {
+            const delayMs = requirePositiveDuration(input.delayMs);
+            const at = schedulerInstantFromMilliseconds(now + delayMs);
+            return { kind: "timer", delayMs, at };
+        }
+        case "once":
+            return { kind: "once", at: parseSchedulerInstant(input.at, "at") };
+        case "interval": {
+            const everyMs = requirePositiveDuration(input.everyMs);
+            const anchorAt = input.anchorAt === undefined
+                ? schedulerInstantFromMilliseconds(now + everyMs)
+                : parseSchedulerInstant(input.anchorAt, "anchorAt");
+            return { kind: "interval", everyMs, anchorAt };
+        }
+        case "daily":
+            return { kind: "daily", at: requireCalendarHour(input.at) };
+        case "weekly": {
+            const weekdays = normalizeWeekdays(input.weekdays);
+            return { kind: "weekly", at: requireCalendarHour(input.at), weekdays };
+        }
+        case "monthly":
+            if (!isSupportedMonthDay(input.dayOfMonth)) {
+                throw new SchedulerValidationError("scheduler_invalid_schedule", "dayOfMonth must be 1–31");
+            }
+            return {
+                kind: "monthly",
+                at: requireCalendarHour(input.at),
+                dayOfMonth: input.dayOfMonth,
+            };
+        default:
+            throw new SchedulerValidationError("scheduler_invalid_schedule", "Unknown schedule kind");
+    }
+}
+/** Stored timer deadlines are canonical state, not new relative timer input. */
+export function normalizeStoredSchedulerSchedule(schedule) {
+    if (schedule?.kind !== "timer")
+        return normalizeSchedulerSchedule(schedule, 0);
+    return {
+        kind: "timer",
+        delayMs: requirePositiveDuration(schedule.delayMs),
+        at: parseSchedulerInstant(schedule.at, "at"),
+    };
+}
+function normalizeWeekdays(value) {
+    if (!Array.isArray(value)) {
+        throw new SchedulerValidationError("scheduler_invalid_schedule", "weekdays must contain Sunday=0 through Saturday=6");
+    }
+    if (value.length === 0) {
+        throw new SchedulerValidationError("scheduler_invalid_schedule", "Choose at least one weekday");
+    }
+    if (!value.every(isSupportedWeekday)) {
+        throw new SchedulerValidationError("scheduler_invalid_schedule", "weekdays must contain integers 0–6");
+    }
+    return [...new Set(value)].sort((a, b) => a - b);
+}
+function isSupportedWeekday(value) {
+    if (!Number.isInteger(value))
+        return false;
+    if (Number(value) < 0)
+        return false;
+    return Number(value) <= 6;
+}
+function isSupportedMonthDay(value) {
+    if (!Number.isInteger(value))
+        return false;
+    if (value < 1)
+        return false;
+    return value <= 31;
+}

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

@@ -0,0 +1,2 @@
+import { type SchedulerContext } from "./service-context.js";
+export declare function tickScheduler(context: SchedulerContext): Promise<void>;