@qilin-agent/schedule 0.0.0-stage → 3.1.4

package/lib/types/runtime.js

@@ -0,0 +1,168 @@
+/** Host timer over stored tasks; Session activation is a delivery operation. */
+import { createUserMessage } from '@qilin-agent/llm';
+import { isRecurringScheduleRecord, renderReminderFraming, renderRecurringReminderBatchFraming, resolveRecurringOccurrence } from "./domain.js";
+import { appendDelivery } from "./delivery-history.js";
+/** Largest delay Node timers represent without clamping. */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** Owns at most one timer across recomputations; delivery and management share the serialized operation. */
+export class ScheduleRuntime {
+    ctx;
+    tasks;
+    transact;
+    commit;
+    retention;
+    timer;
+    running;
+    stopping = false;
+    requested = false;
+    /**
+     * @param ctx - Host services used to resume and enqueue.
+     * @param tasks - Current durable tasks.
+     * @param transact - Serialize delivery against management writes.
+     * @param commit - Persist task status, target, receipt, and history together after durable inbox delivery.
+     */
+    constructor(ctx, tasks, transact, commit, retention) {
+        this.ctx = ctx;
+        this.tasks = tasks;
+        this.transact = transact;
+        this.commit = commit;
+        this.retention = retention;
+    }
+    /**
+     * Recompute the nearest obligation after startup or a durable change.
+     * Dispatch failures are logged; refused admission does not retry automatically.
+     */
+    requestDrive() {
+        if (this.stopping)
+            return;
+        this.requested = true;
+        this.clearTimer();
+        if (this.running !== undefined)
+            return;
+        let run;
+        try {
+            run = this.ctx.agents.withoutInitiator(async () => {
+                while (this.requested && !this.stopping) {
+                    this.requested = false;
+                    await this.transact(async () => { await this.drive(); });
+                }
+            });
+        }
+        catch (error) {
+            // Ancestor unloading closes initiator admission before runtime cleanup runs.
+            this.requested = false;
+            this.ctx.logger.warn(`schedule: dispatch stopped: ${String(error)}`);
+            return;
+        }
+        this.running = run;
+        void run.catch((error) => {
+            this.ctx.logger.warn(`schedule: dispatch stopped: ${String(error)}`);
+        }).finally(() => {
+            this.running = undefined;
+            if (this.requested && !this.stopping)
+                this.requestDrive();
+        });
+    }
+    /** Stop the timer and drain an accepted delivery before storage closes. */
+    async dispose() {
+        this.stopping = true;
+        this.clearTimer();
+        // requestDrive reports execution failures; teardown only waits for quiescence.
+        await this.running?.catch(() => undefined);
+    }
+    clearTimer() {
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    async drive() {
+        this.clearTimer();
+        const failed = new Set();
+        const handled = new Set();
+        const scanNow = Date.now();
+        const due = this.tasks().filter(task => task.status === 'active' && Date.parse(task.record.scheduledAt) <= scanNow);
+        for (const task of due) {
+            if (this.stopping)
+                return;
+            if (handled.has(task.record.id))
+                continue;
+            const group = isRecurringScheduleRecord(task.record)
+                ? due.filter(candidate => candidate.sessionId === task.sessionId && isRecurringScheduleRecord(candidate.record))
+                : [task];
+            for (const member of group)
+                handled.add(member.record.id);
+            let admitted = group;
+            const committed = new Set();
+            try {
+                const resolved = await this.ctx.sessionController.resolveAgent(task.sessionId);
+                if ('error' in resolved)
+                    throw resolved.error;
+                // oxlint-disable-next-line typescript/no-unnecessary-condition -- Disposal can run while Session restoration is awaited.
+                if (this.stopping)
+                    return;
+                const now = Date.now();
+                // Session restoration can span a wall-clock rollback; future members keep their timer obligation.
+                admitted = group.filter(member => Date.parse(member.record.scheduledAt) <= now);
+                if (admitted.length === 0)
+                    continue;
+                const recurring = admitted.filter((member) => isRecurringScheduleRecord(member.record));
+                const occurrences = recurring.map(member => ({
+                    task: member, occurrence: resolveRecurringOccurrence(member.record, now),
+                }));
+                const text = isRecurringScheduleRecord(task.record)
+                    ? renderRecurringReminderBatchFraming(occurrences.map(({ task: member, occurrence }) => ({
+                        record: member.record, occurrenceAt: occurrence.occurrenceAt,
+                    })))
+                    : renderReminderFraming(task.record);
+                const message = createUserMessage({
+                    content: [{ type: 'text', text }], source: { kind: 'schedule' },
+                });
+                // followup synchronously appends the inbox splice before flush observes the Session.
+                resolved.agent.followup(message);
+                const flushed = await this.ctx.sessions.flush(resolved.agent.session);
+                if (!flushed)
+                    throw new Error('Session persistence did not acknowledge the reminder');
+                const deliveredAt = new Date(Date.now()).toISOString();
+                if (!isRecurringScheduleRecord(task.record)) {
+                    await this.commit({
+                        ...task, status: 'inactive',
+                        ...appendDelivery(task, { scheduledAt: task.record.scheduledAt, deliveredAt, messageId: message.id }, this.retention),
+                    });
+                    committed.add(task.record.id);
+                }
+                for (const { task: member, occurrence } of occurrences) {
+                    await this.commit({
+                        ...member,
+                        record: { ...member.record, scheduledAt: occurrence.nextScheduledAt ?? occurrence.occurrenceAt },
+                        status: occurrence.nextScheduledAt === undefined ? 'inactive' : 'active',
+                        ...appendDelivery(member, { scheduledAt: occurrence.occurrenceAt, deliveredAt, messageId: message.id }, this.retention),
+                    });
+                    committed.add(member.record.id);
+                }
+            }
+            catch (error) {
+                // Successful commits and targets made future by clock rollback keep their timer obligation.
+                const pending = admitted.filter(member => !committed.has(member.record.id));
+                const failedAt = Date.now();
+                for (const member of pending) {
+                    if (Date.parse(member.record.scheduledAt) <= failedAt)
+                        failed.add(member.record.id);
+                }
+                const ids = pending.map(member => member.record.id);
+                this.ctx.logger.warn(`schedule: reminders ${JSON.stringify(ids)} were not acknowledged: ${String(error)}`);
+            }
+        }
+        if (this.stopping)
+            return;
+        const next = this.tasks().filter(task => task.status === 'active' && !failed.has(task.record.id))
+            .reduce((at, task) => {
+            const target = Date.parse(task.record.scheduledAt);
+            return at === undefined ? target : Math.min(at, target);
+        }, undefined);
+        if (next !== undefined) {
+            this.timer = setTimeout(() => { this.timer = undefined; this.requestDrive(); }, Math.max(0, Math.min(next - Date.now(), MAX_TIMER_DELAY_MS)));
+            this.timer.unref();
+        }
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/lib/types/storage.d.ts

@@ -0,0 +1,59 @@
+/** Durable Host-wide Schedule tasks, independently of Session activation. */
+import { z } from 'zod';
+import { SessionId } from '@qilin-agent/session';
+import { MessageId } from '@qilin-agent/llm/brand';
+import type { ScheduleId } from './types.ts';
+/** Stored task binds one schedule to its original Session; absent status decodes as active. */
+export declare const scheduleTaskSchema: z.ZodObject<{
+    sessionId: z.ZodPipe<z.ZodString, z.ZodTransform<SessionId, string>>;
+    record: z.ZodPipe<z.ZodUnknown, z.ZodTransform<import("./types.ts").AfterScheduleRecord | import("./types.ts").AtScheduleRecord | import("./types.ts").EveryScheduleRecord | import("./types.ts").DailyScheduleRecord | import("./types.ts").WeeklyScheduleRecord | import("./types.ts").CronScheduleRecord, unknown>>;
+    status: z.ZodDefault<z.ZodEnum<{
+        active: "active";
+        inactive: "inactive";
+    }>>;
+    lastDelivery: z.ZodOptional<z.ZodObject<{
+        scheduledAt: z.ZodISODateTime;
+        deliveredAt: z.ZodISODateTime;
+        messageId: z.ZodPipe<z.ZodString, z.ZodTransform<MessageId, string>>;
+    }, z.core.$strict>>;
+    deliveryHistory: z.ZodOptional<z.ZodObject<{
+        records: z.ZodArray<z.ZodObject<{
+            scheduledAt: z.ZodISODateTime;
+            deliveredAt: z.ZodISODateTime;
+            messageId: z.ZodPipe<z.ZodString, z.ZodTransform<MessageId, string>>;
+            prompt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        earlierRecordsUnavailable: z.ZodBoolean;
+        earlierRecordsPruned: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Persistent task value; absent history retains only its legacy last receipt without a read-time rewrite. */
+export type ScheduleTask = z.infer<typeof scheduleTaskSchema>;
+/** Authoritative Schedule storage; malformed tasks reject opening the domain. */
+export declare const scheduleDomain: {
+    name: string;
+    version: number;
+    tables: {
+        tasks: import("@qilin-agent/storage-domain").DomainTableSpec<ScheduleId, {
+            sessionId: SessionId;
+            record: import("./types.ts").AfterScheduleRecord | import("./types.ts").AtScheduleRecord | import("./types.ts").EveryScheduleRecord | import("./types.ts").DailyScheduleRecord | import("./types.ts").WeeklyScheduleRecord | import("./types.ts").CronScheduleRecord;
+            status: "active" | "inactive";
+            lastDelivery?: {
+                scheduledAt: string;
+                deliveredAt: string;
+                messageId: MessageId;
+            } | undefined;
+            deliveryHistory?: {
+                records: {
+                    scheduledAt: string;
+                    deliveredAt: string;
+                    messageId: MessageId;
+                    prompt?: string | undefined;
+                }[];
+                earlierRecordsUnavailable: boolean;
+                earlierRecordsPruned?: boolean | undefined;
+            } | undefined;
+        }>;
+    };
+};
+//# sourceMappingURL=storage.d.ts.map

package/lib/types/storage.js

@@ -0,0 +1,54 @@
+/** Durable Host-wide Schedule tasks, independently of Session activation. */
+import { z } from 'zod';
+import { SessionId } from '@qilin-agent/session';
+import { MessageId } from '@qilin-agent/llm/brand';
+import { defineDomain, domainTable } from '@qilin-agent/storage-domain';
+import { decodeScheduleRecord } from "./domain.js";
+const recordSchema = z.unknown().transform((value, context) => {
+    try {
+        return decodeScheduleRecord(value);
+    }
+    catch (error) {
+        context.addIssue({ code: 'custom', message: String(error) });
+    }
+    return z.NEVER;
+});
+const instantSchema = z.iso.datetime({ precision: 3 }).refine(value => !value.startsWith('0000-'), {
+    message: 'Expected a canonical four-digit-year UTC calendar instant',
+});
+const deliveryReceiptSchema = z.object({
+    scheduledAt: instantSchema,
+    deliveredAt: instantSchema,
+    messageId: z.string().min(1).refine(value => value.trim() === value).transform(MessageId),
+}).strict();
+const deliveryHistorySchema = z.object({
+    records: z.array(deliveryReceiptSchema.extend({ prompt: z.string().optional() }).strict()),
+    earlierRecordsUnavailable: z.boolean(),
+    earlierRecordsPruned: z.boolean().optional(),
+}).strict().refine(history => new Set(history.records.map(record => record.messageId)).size === history.records.length, {
+    message: 'Delivery history message identities must be unique within a task',
+});
+/** Stored task binds one schedule to its original Session; absent status decodes as active. */
+export const scheduleTaskSchema = z.object({
+    sessionId: z.string().min(1).transform(SessionId),
+    record: recordSchema,
+    status: z.enum(['active', 'inactive']).default('active'),
+    lastDelivery: deliveryReceiptSchema.optional(),
+    deliveryHistory: deliveryHistorySchema.optional(),
+}).strict().refine((task) => {
+    if (task.deliveryHistory === undefined)
+        return true;
+    const latest = task.deliveryHistory.records.at(-1);
+    if (latest === undefined)
+        return task.lastDelivery === undefined;
+    return task.lastDelivery !== undefined
+        && latest.scheduledAt === task.lastDelivery.scheduledAt
+        && latest.deliveredAt === task.lastDelivery.deliveredAt
+        && latest.messageId === task.lastDelivery.messageId;
+}, { message: 'Last delivery must match the latest saved delivery receipt' });
+/** Authoritative Schedule storage; malformed tasks reject opening the domain. */
+export const scheduleDomain = defineDomain({
+    name: 'schedule', version: 1,
+    tables: { tasks: domainTable(scheduleTaskSchema) },
+});
+//# sourceMappingURL=storage.js.map