@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/schedule/cron.js

@@ -0,0 +1,114 @@
+import { parseCronExpression } from "@hyperdrive.bot/fleet-protocol/schedule/cron-expression";
+function startOfNextMinute(date) {
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate(), date.getUTCHours(), date.getUTCMinutes() + 1, 0, 0));
+}
+function assertValidTimeZone(timeZone) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone }).format(new Date(0));
+    }
+    catch {
+        throw new Error(`Invalid cron time zone: ${timeZone}`);
+    }
+}
+function createCronDatePartsReader(timeZone) {
+    if (timeZone === undefined) {
+        return (date) => ({
+            minute: date.getUTCMinutes(),
+            hour: date.getUTCHours(),
+            dayOfMonth: date.getUTCDate(),
+            month: date.getUTCMonth() + 1,
+            dayOfWeek: date.getUTCDay(),
+        });
+    }
+    assertValidTimeZone(timeZone);
+    const formatter = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hourCycle: "h23",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+    });
+    return (date) => {
+        const values = {};
+        for (const part of formatter.formatToParts(date)) {
+            if (part.type !== "literal") {
+                values[part.type] = part.value;
+            }
+        }
+        const year = Number.parseInt(values.year, 10);
+        const month = Number.parseInt(values.month, 10);
+        const dayOfMonth = Number.parseInt(values.day, 10);
+        return {
+            minute: Number.parseInt(values.minute, 10),
+            hour: Number.parseInt(values.hour, 10),
+            dayOfMonth,
+            month,
+            dayOfWeek: new Date(Date.UTC(year, month - 1, dayOfMonth)).getUTCDay(),
+        };
+    };
+}
+export function validateScheduleCadence(cadence, resolvers) {
+    switch (cadence.type) {
+        case "every":
+            return;
+        case "cron": {
+            parseCronExpression(cadence.expression);
+            if (cadence.timezone !== undefined) {
+                assertValidTimeZone(cadence.timezone);
+            }
+            return;
+        }
+        case "source": {
+            // Zod already enforced non-empty ids, so with no resolvers this is a
+            // shape-only validation rather than a silent pass.
+            if (resolvers?.sourceExists && !resolvers.sourceExists(cadence.sourceId)) {
+                throw new Error(`Unknown ingestion source: ${cadence.sourceId}`);
+            }
+            if (resolvers?.filterExists && !resolvers.filterExists(cadence.filterId)) {
+                throw new Error(`Unknown filter: ${cadence.filterId}`);
+            }
+            return;
+        }
+        default: {
+            const _exhaustive = cadence;
+            throw new Error(`Unhandled cadence: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}
+// Returns null when the cadence has no next run of its own — a push-only source
+// filter parks on nextRunAt: null and is woken by ingestion, not by the clock.
+export function computeNextRunAt(cadence, after) {
+    switch (cadence.type) {
+        case "every":
+            return new Date(after.getTime() + cadence.everyMs);
+        case "source":
+            return cadence.pollEveryMs === undefined
+                ? null
+                : new Date(after.getTime() + cadence.pollEveryMs);
+        case "cron": {
+            const cron = parseCronExpression(cadence.expression);
+            const readDateParts = createCronDatePartsReader(cadence.timezone);
+            const limit = 366 * 24 * 60;
+            let cursor = startOfNextMinute(after);
+            for (let index = 0; index < limit; index += 1) {
+                const { minute, hour, dayOfMonth, month, dayOfWeek } = readDateParts(cursor);
+                if (cron.minute.matches(minute) &&
+                    cron.hour.matches(hour) &&
+                    cron.dayOfMonth.matches(dayOfMonth) &&
+                    cron.month.matches(month) &&
+                    cron.dayOfWeek.matches(dayOfWeek)) {
+                    return cursor;
+                }
+                cursor = new Date(cursor.getTime() + 60000);
+            }
+            throw new Error(`Unable to compute next run time for cron expression: ${cadence.expression}`);
+        }
+        default: {
+            const _exhaustive = cadence;
+            throw new Error(`Unhandled cadence: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}
+//# sourceMappingURL=cron.js.map

package/dist/server/server/schedule/service.d.ts

@@ -0,0 +1,207 @@
+import type { Logger } from "pino";
+import { AgentManager } from "../agent/agent-manager.js";
+import type { AgentStorage } from "../agent/agent-storage.js";
+import type { ProviderSnapshotManager } from "../agent/provider-snapshot-manager.js";
+import type { StoredFilter } from "@hyperdrive.bot/fleet-protocol/ingestion/filter-types";
+import type { MatchedItem } from "../ingestion/types.js";
+import type { IngestionLedgerMaintenance } from "../ingestion/ledger.js";
+import type { CapLimiterAdmit } from "../ingestion/cap-limiter.js";
+import type { CreateScheduleInput, ScheduleExecutionResult, ScheduleRun, ScheduleTargetNewAgentConfig, StoredSchedule, UpdateScheduleInput } from "@hyperdrive.bot/fleet-protocol/schedule/types";
+export declare class ScheduleTargetGoneError extends Error {
+    constructor(message: string);
+}
+export declare class ScheduleRunOnCreateUnsupportedError extends Error {
+    constructor(message: string);
+}
+/**
+ * The two schedule-derived facts about an agent, built together.
+ *
+ * They are separate fields because they answer different questions and a paused
+ * schedule splits them: `nextFireAt` is the DISPLAY value ("when does this next
+ * fire", which for a paused schedule is never), `routineAgentIds` is the
+ * CLASSIFIER ("does this agent have a routine at all", which a paused schedule
+ * still satisfies). One field doing both jobs is what made `pause_schedule`
+ * silently demote an agent to a session.
+ */
+export interface AgentScheduleFacts {
+    /** Earliest upcoming fire per targeted agent id. Absent key = nothing will fire. */
+    nextFireAtByAgent: ReadonlyMap<string, string>;
+    /** Agent ids with at least one active OR paused schedule targeting them. */
+    routineAgentIds: ReadonlySet<string>;
+}
+type CreateConfigResolver = Pick<ProviderSnapshotManager, "resolveCreateConfig">;
+export interface ScheduleServiceOptions {
+    paseoHome: string;
+    logger: Logger;
+    agentManager: AgentManager;
+    agentStorage: AgentStorage;
+    providerSnapshotManager: CreateConfigResolver;
+    now?: () => Date;
+    /**
+     * Boot-time ingestion-ledger maintenance. Structural on purpose: this service
+     * depends on the narrow `IngestionLedgerMaintenance` view and never on the
+     * concrete class, so a `node:sqlite` failure cannot break this module's
+     * resolution. Omitted in every test that does not care, and in that case no
+     * ledger module is loaded at all.
+     */
+    ledger?: IngestionLedgerMaintenance;
+    /**
+     * The daemon's single runs/day limiter, carried through rather than used here.
+     *
+     * Story 3.4 constructs exactly one in `bootstrap.ts` and hands it to this
+     * service so the AUTOMATIC path (the tick, which lives here) and the MANUAL
+     * path (Epic 5's RPC, which already receives `scheduleService`) reach the same
+     * instance. Nothing in this file calls `admit`: Epic 2 owns the dispatch loop,
+     * and the alternatives to this option are both worse - a module-level
+     * singleton is hidden global state, and re-constructing the limiter in Epic 2
+     * is the exact second instance Story 3.4 exists to forbid.
+     *
+     * `import type` only, like `ledger` above, so a sqlite failure cannot break
+     * this module's resolution.
+     */
+    capLimiter?: CapLimiterAdmit;
+    /**
+     * Boot-time cohort resume, as a CALLBACK rather than a `CohortStore` import.
+     *
+     * Deliberate, and one edit more than the epic's "one additive call": the
+     * rollback plan for Story 5.4 is "delete the resume call, and `cohort-store.ts`
+     * becomes dead code nothing imports". That is only true if this module never
+     * names the module. A direct import would leave a rollback with a dangling
+     * import and a compile error; the callback keeps it to deleting one line.
+     *
+     * Omitted by every test that does not care, and by any daemon with no ledger.
+     */
+    cohortResumer?: () => Promise<void>;
+    runner?: (schedule: StoredSchedule, runId: string) => Promise<ScheduleExecutionResult>;
+    /**
+     * Source-cadence seams. Epic 5 supplies the real filter store; Epic 3 replaces the
+     * item provider with the ledger.
+     *
+     * `filterResolver` defaults to a throw rather than to a no-op returning null: a
+     * silent null would mint a session carrying `schedule.prompt` and no brief, which is
+     * exactly the failure this path exists to prevent.
+     *
+     * `matchedItems` hands over UNGROUPED items and defaults to yielding none. Collapsing
+     * them is this service's job, not the provider's. The count a caller is shown and
+     * the group that dispatches have to come out of one function. A tick that matches
+     * nothing is ordinary, so an empty array is a normal answer, not an error.
+     */
+    filterResolver?: (filterId: string) => Promise<StoredFilter | null>;
+    matchedItems?: (schedule: StoredSchedule, filter: StoredFilter) => Promise<MatchedItem[]>;
+}
+export declare class ScheduleService {
+    private readonly store;
+    private readonly logger;
+    private readonly agentManager;
+    private readonly agentStorage;
+    private readonly createConfigResolver;
+    private readonly now;
+    private readonly runner;
+    private readonly filterResolver;
+    private readonly matchedItems;
+    private readonly ledger;
+    private readonly capLimiter;
+    private readonly cohortResumer;
+    private readonly runningScheduleIds;
+    private tickTimer;
+    /**
+     * Last computed schedule facts per agent, refreshed on every tick (1s) and on
+     * demand. `null` until the first read, which is what lets `peekNextFireAt` and
+     * `peekHasRoutine` tell "no schedule targets this agent" apart from "nobody has
+     * looked yet" - the agent predicate treats those the same, but only one of them
+     * is a claim about the agent.
+     *
+     * ONE cache for BOTH facts on purpose: they are built in a single pass, so
+     * neither can be fresh while the other is stale.
+     */
+    private agentScheduleFacts;
+    constructor(options: ScheduleServiceOptions);
+    /**
+     * The daemon's one runs/day limiter, or undefined when the ledger is.
+     *
+     * The accessor exists so Epic 2's dispatch loop and Epic 5's confirmation
+     * screen reach the SAME instance through plumbing that already exists, instead
+     * of constructing their own.
+     */
+    getCapLimiter(): CapLimiterAdmit | undefined;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    create(input: CreateScheduleInput): Promise<StoredSchedule>;
+    createOrReplace(input: CreateScheduleInput): Promise<StoredSchedule>;
+    list(): Promise<StoredSchedule[]>;
+    /**
+     * Read the schedule store and return BOTH schedule facts per targeted agent id,
+     * refreshing the cache `peekNextFireAt` and `peekHasRoutine` serve.
+     *
+     * This is the seam the agent projections use for `nextFireAt` and `hasRoutine`.
+     * Those projections are pure and synchronous while this store is async and
+     * file-backed, so the caller that already awaits does the join ONCE per batch
+     * and passes each agent its own answer down. Both facts come off the same
+     * listing, so a caller can never get one refreshed and the other stale.
+     */
+    listAgentScheduleFacts(): Promise<AgentScheduleFacts>;
+    /**
+     * Synchronous read of the cached next-fire index, for the projection paths that
+     * are not async and cannot await a store read.
+     *
+     * Returns `undefined` when the index has never been built (no tick yet, no
+     * explicit refresh), which the wire schema defines as "not computed". Returns
+     * `null` only when the index HAS been built and holds no active schedule for
+     * this agent. Staleness is bounded by the tick interval once `start()` has run.
+     */
+    peekNextFireAt(agentId: string): string | null | undefined;
+    /**
+     * Synchronous read of the cached routine set: does any active OR paused
+     * schedule target this agent.
+     *
+     * Same `undefined` = "never computed" contract as `peekNextFireAt`, and served
+     * off the same cache entry so the two answers always describe the same listing.
+     */
+    peekHasRoutine(agentId: string): boolean | undefined;
+    inspect(id: string): Promise<StoredSchedule>;
+    logs(id: string): Promise<ScheduleRun[]>;
+    pause(id: string): Promise<StoredSchedule>;
+    resume(id: string): Promise<StoredSchedule>;
+    update(input: UpdateScheduleInput): Promise<StoredSchedule>;
+    delete(id: string): Promise<void>;
+    completeForAgent(agentId: string): Promise<number>;
+    runOnce(id: string): Promise<StoredSchedule>;
+    tick(): Promise<void>;
+    private recoverInterruptedRuns;
+    private sweepOrphanedSchedules;
+    private runSchedule;
+    private finishRun;
+    private executeSchedule;
+    /**
+     * A dead `cwd` is a permanently gone target, not a transient failure.
+     *
+     * Split out so `executeSchedule` can fire it ahead of source-filter resolution
+     * while `runUnattendedSession` still owns it for every other caller.
+     */
+    private assertTargetCwdExists;
+    /**
+     * Mint one unattended session against a `new-agent` target, run it, archive it,
+     * and hand back the curated output.
+     *
+     * This is the ONE new-agent minting path in the daemon. The overnight tick
+     * reaches it through `executeSchedule`; Epic 5's manual dry run reaches it
+     * directly as a `DryRunDispatcher`, which `ScheduleService` satisfies
+     * structurally with no adapter class. A second copy of this block is how the
+     * two paths would drift on `unattended`, on archival, or on title derivation.
+     *
+     * The caller owns the prompt and the labels. This method owns everything that
+     * touches the provider.
+     */
+    runUnattendedSession(input: {
+        targetConfig: ScheduleTargetNewAgentConfig;
+        prompt: string;
+        labels: Record<string, string>;
+        mcpServersOverride?: Record<string, unknown>;
+    }): Promise<{
+        agentId: string;
+        output: string | null;
+    }>;
+    private resolveProviderCreateConfig;
+}
+export {};
+//# sourceMappingURL=service.d.ts.map