@qilin-agent/schedule 0.0.0-stage → 3.1.3

package/lib/types/index.d.ts

@@ -0,0 +1,134 @@
+import z from '@qilin-agent/schemastery';
+import { Context, Service } from '@qilin-agent/kylin';
+import { TypertRemoteService } from '@qilin-agent/typert-protocol';
+import type { SessionId } from '@qilin-agent/session';
+import type { ScheduleCatalogEntry, ScheduleCreateRequest, ScheduleDeleteRequest, ScheduleDeleteResult, ScheduleDeliveryHistoryRequest, ScheduleDeliveryHistoryResult, ScheduleListRequest, ScheduleRecord, ScheduleUpdateRequest, ScheduleUpdateResult } from './types.ts';
+export type * from './types.ts';
+export { scheduleDomain } from './storage.ts';
+export type { ScheduleTask } from './storage.ts';
+export type { RecurringOccurrence } from './domain.ts';
+export { SCHEDULE_CHANGE_VERSION, MIN_EVERY_INTERVAL_SECONDS, MAX_TITLE_LENGTH, REQUIRED_TITLE_MESSAGE, ScheduleId, ScheduleInputError, ScheduleLogError, canonicalizeCronExpression, createAfterScheduleRecord, createAtScheduleRecord, createEveryScheduleRecord, createDailyScheduleRecord, createWeeklyScheduleRecord, createCronScheduleRecord, decodeScheduleChange, decodeScheduleRecord, foldScheduleEvents, isRecurringScheduleRecord, normalizeWeekdays, parseCronInput, parseWeeklyInput, renderReminderFraming, renderRecurringReminderBatchFraming, resolveEveryOccurrence, resolveDailyOccurrence, resolveWeeklyOccurrence, resolveCronOccurrence, resolveRecurringOccurrence, scheduleTitle, scheduleView, weeklyTime, } from './domain.ts';
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        /** Durable Host-wide reminder management. */
+        schedule: ScheduleService;
+    }
+}
+/** Configuration for the Host Schedule domain. */
+export interface Config {
+    /**
+     * Delivery-history window retained per task, in days; omission defaults to 30.
+     * Pruning happens when an acknowledgment is appended, and `lastDelivery` is always retained.
+     */
+    deliveryHistoryDays?: number;
+    /**
+     * Retained delivery records per task; omission defaults to 200. The older of this
+     * cap and the window wins, and the newest records survive.
+     */
+    deliveryHistoryRecords?: number;
+}
+/**
+ * Shared management service; reads, deletion, and timing edits never activate a Session.
+ *
+ * `sessionPersistence` is a load-order requirement rather than a directly called
+ * service: a delivery commits only when `ctx.sessions.flush()` reports that a
+ * `session/flush` listener participated, and the persistence backend providing this
+ * service is the plugin that registers that listener.
+ */
+export declare class ScheduleService extends TypertRemoteService {
+    static inject: string[];
+    static Config: z<Config>;
+    /** Resolved retention bounds shared with the runtime that appends acknowledgments. */
+    private readonly retention;
+    private readonly ready;
+    private readonly initialized;
+    private chain;
+    private runtime;
+    private stopping;
+    /**
+     * @param ctx - Host services owning storage, dispatch, and Session restoration.
+     * @param config - Validated retention configuration for delivery history.
+     */
+    constructor(ctx: Context, config: Config);
+    [Service.init](): Promise<void>;
+    /**
+     * Create a reminder bound to the caller-selected Session without activating it.
+     *
+     * The request must supply a title; a missing, blank-after-trim, or over-long
+     * title rejects with `invalid_prompt` instead of deriving one from the prompt.
+     * The record is built from the clock reading taken before the request joins the
+     * serialized queue, so a create that waits behind a longer operation keeps its
+     * request-time anchor and may already be due when the queue reaches it.
+     * @param sessionId - Original Session receiving the reminder.
+     * @param request - Validated tool selector, required title, and reminder content.
+     * @param signal - Optional cancellation checked before persistence begins, including after FIFO waits.
+     * @returns The durably stored schedule. Cancellation does not roll back an in-flight write.
+     */
+    create(sessionId: SessionId, request: ScheduleCreateRequest, signal?: AbortSignal): Promise<ScheduleRecord>;
+    /**
+     * Read the selected Session's active tasks without resuming its Agent.
+     * @param request - Session whose task list is requested.
+     * @returns Persisted reminders in storage order.
+     */
+    list(request: ScheduleListRequest): Promise<ScheduleRecord[]>;
+    /**
+     * Read all active and inactive Host reminders with their original Session bindings.
+     * A deleted reminder has no row, so it is absent here.
+     * Does not activate Sessions or read Session history.
+     * @returns Reminders ordered by scheduledAt ascending, then lexicographically by id.
+     */
+    catalog(): Promise<ScheduleCatalogEntry[]>;
+    /**
+     * Read saved inbox deliveries without activating or reading the original Session.
+     * The task's own row supplies its binding, so its records stay readable through this lookup.
+     * @param request - Session binding, task identity, explicit limit, and optional exclusive message cursor.
+     * @returns Newest-first deliveries in append order, or a task/cursor lookup failure.
+     * @throws ScheduleInputError when limit is not a safe integer from 1 through 100.
+     */
+    history(request: ScheduleDeliveryHistoryRequest): Promise<ScheduleDeliveryHistoryResult>;
+    /**
+     * Delete one task belonging to the selected Session, leaving queued messages intact.
+     *
+     * The row is removed: the task no longer schedules, leaves `list` and `catalog`, and its
+     * saved delivery records go with it.
+     * @param request - Session and exact task identity.
+     * @param signal - Optional cancellation checked before persistence begins, including after FIFO waits.
+     * @returns Whether that Session owned a deleted task. Cancellation does not roll back an in-flight write.
+     */
+    delete(request: ScheduleDeleteRequest, signal?: AbortSignal): Promise<ScheduleDeleteResult>;
+    /**
+     * Update the name, instruction, and timing of an active task within the original Session
+     * binding without activating the Session or changing saved deliveries.
+     *
+     * Each supplied field replaces its stored value; an omitted field keeps it. A name or
+     * instruction change alone does not reset the committed target.
+     * @param request - Task binding, complete observed record, and any combination of timing, name, and instruction.
+     * @param signal - Cancellation checked after domain readiness and FIFO waits, before persistence begins.
+     * @returns The committed record, unchanged record for a no-op, or a non-mutating input/lookup/conflict result.
+     * Storage and lifecycle failures reject; cancellation after a write starts does not roll it back.
+     */
+    update(request: ScheduleUpdateRequest, signal?: AbortSignal): Promise<ScheduleUpdateResult>;
+    /**
+     * Dispatch one post-commit `schedule/changed` notification, containing
+     * synchronous listener failures: every call site emits only after its durable
+     * task write landed, so a throwing listener must not reject the caller or
+     * skip the following `requestDrive()`.
+     */
+    private emitChanged;
+    private getDomain;
+    /**
+     * Remove every active task stored for one Session, inside the queue the tools
+     * use.
+     *
+     * Enumerating and deleting in one queue slot is what makes an archive stop
+     * ordered behind a create whose write is still in flight: a stop that read the
+     * table outside the queue could miss a row the create was about to commit and
+     * leave an armed reminder behind. Re-entering the public `delete()` from here
+     * would deadlock on this queue, so the rows are removed directly.
+     * @param sessionId - Session whose active Host tasks must stop.
+     */
+    private stopSessionTasks;
+    private serialize;
+}
+export default ScheduleService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,416 @@
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+/** Host-wide durable reminders and shared human/model management. */
+import { randomUUID } from 'node:crypto';
+import z from '@qilin-agent/schemastery';
+import { Service } from '@qilin-agent/kylin';
+import { TypertRemoteService, Remote } from '@qilin-agent/typert-protocol';
+import { ScheduleRuntime } from "./runtime.js";
+import { scheduleDomain } from "./storage.js";
+import { deliveryHistoryPage } from "./delivery-history.js";
+import { resolveScheduleUpdate } from "./update.js";
+import { foldScheduleEvents, ScheduleInputError, ScheduleLogError, ScheduleId, createAfterScheduleRecord, createAtScheduleRecord, createEveryScheduleRecord, createDailyScheduleRecord, createWeeklyScheduleRecord, createCronScheduleRecord, scheduleTitle, } from "./domain.js";
+export { scheduleDomain } from "./storage.js";
+export { SCHEDULE_CHANGE_VERSION, MIN_EVERY_INTERVAL_SECONDS, MAX_TITLE_LENGTH, REQUIRED_TITLE_MESSAGE, ScheduleId, ScheduleInputError, ScheduleLogError, canonicalizeCronExpression, createAfterScheduleRecord, createAtScheduleRecord, createEveryScheduleRecord, createDailyScheduleRecord, createWeeklyScheduleRecord, createCronScheduleRecord, decodeScheduleChange, decodeScheduleRecord, foldScheduleEvents, isRecurringScheduleRecord, normalizeWeekdays, parseCronInput, parseWeeklyInput, renderReminderFraming, renderRecurringReminderBatchFraming, resolveEveryOccurrence, resolveDailyOccurrence, resolveWeeklyOccurrence, resolveCronOccurrence, resolveRecurringOccurrence, scheduleTitle, scheduleView, weeklyTime, } from "./domain.js";
+/** Retained delivery-history window applied when the deployment states none. */
+const DEFAULT_DELIVERY_HISTORY_DAYS = 30;
+/** Retained delivery-history record cap applied when the deployment states none. */
+const DEFAULT_DELIVERY_HISTORY_RECORDS = 200;
+/**
+ * Shared management service; reads, deletion, and timing edits never activate a Session.
+ *
+ * `sessionPersistence` is a load-order requirement rather than a directly called
+ * service: a delivery commits only when `ctx.sessions.flush()` reports that a
+ * `session/flush` listener participated, and the persistence backend providing this
+ * service is the plugin that registers that listener.
+ */
+let ScheduleService = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _list_decorators;
+    let _catalog_decorators;
+    let _history_decorators;
+    let _delete_decorators;
+    let _update_decorators;
+    return class ScheduleService extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _list_decorators = [Remote('list')];
+            _catalog_decorators = [Remote('catalog')];
+            _history_decorators = [Remote('history')];
+            _delete_decorators = [Remote('delete')];
+            _update_decorators = [Remote('update')];
+            __esDecorate(this, null, _list_decorators, { kind: "method", name: "list", static: false, private: false, access: { has: obj => "list" in obj, get: obj => obj.list }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _catalog_decorators, { kind: "method", name: "catalog", static: false, private: false, access: { has: obj => "catalog" in obj, get: obj => obj.catalog }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _history_decorators, { kind: "method", name: "history", static: false, private: false, access: { has: obj => "history" in obj, get: obj => obj.history }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _delete_decorators, { kind: "method", name: "delete", static: false, private: false, access: { has: obj => "delete" in obj, get: obj => obj.delete }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _update_decorators, { kind: "method", name: "update", static: false, private: false, access: { has: obj => "update" in obj, get: obj => obj.update }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        static inject = ['agents', 'sessions', 'tools', 'storageDomain', 'sessionController', 'sessionPersistence'];
+        static Config = z.object({
+            deliveryHistoryDays: z.number().step(1).min(1).max(3650).default(DEFAULT_DELIVERY_HISTORY_DAYS),
+            deliveryHistoryRecords: z.number().step(1).min(1).max(10_000).default(DEFAULT_DELIVERY_HISTORY_RECORDS),
+        });
+        /** Resolved retention bounds shared with the runtime that appends acknowledgments. */
+        retention = __runInitializers(this, _instanceExtraInitializers);
+        ready;
+        initialized;
+        chain = Promise.resolve();
+        runtime;
+        stopping = false;
+        /**
+         * @param ctx - Host services owning storage, dispatch, and Session restoration.
+         * @param config - Validated retention configuration for delivery history.
+         */
+        constructor(ctx, config) {
+            super(ctx, 'schedule');
+            this.retention = {
+                days: config.deliveryHistoryDays ?? DEFAULT_DELIVERY_HISTORY_DAYS,
+                records: config.deliveryHistoryRecords ?? DEFAULT_DELIVERY_HISTORY_RECORDS,
+            };
+            this.ready = ctx.storageDomain.open(scheduleDomain).then(async (domain) => {
+                for (const [key, task] of domain.table('tasks').entries()) {
+                    if (key !== task.record.id) {
+                        // The mismatch is the actionable failure; a rejecting close must not replace it.
+                        try {
+                            await domain.close();
+                        }
+                        catch (error) {
+                            ctx.logger.warn(`schedule: closing the domain after a key mismatch failed: ${String(error)}`);
+                        }
+                        throw new Error(`schedule: stored task key "${key}" differs from record id "${task.record.id}"`);
+                    }
+                }
+                return domain;
+            });
+            this.initialized = ctx.effect(async () => {
+                const domain = await this.ready;
+                let cleanup;
+                try {
+                    cleanup = ctx.effect(() => async () => {
+                        this.stopping = true;
+                        await this.runtime?.dispose();
+                        await this.chain; // The chain contains failures after returning them to their callers.
+                        await domain.close();
+                    });
+                }
+                catch (error) {
+                    this.stopping = true;
+                    await domain.close();
+                    throw error;
+                }
+                const tasks = domain.table('tasks');
+                this.runtime = new ScheduleRuntime(ctx, () => [...tasks.entries()].map(([, task]) => task), work => this.serialize(work), async (task) => {
+                    await tasks.put(task.record.id, task);
+                    this.emitChanged();
+                }, this.retention);
+                this.runtime.requestDrive();
+                return cleanup;
+            });
+            ctx.on('session/created', (session) => {
+                // Historical Schedule events remain readable but do not populate Host tasks.
+                // A throwing `session/created` listener rolls the attach back, so an unreadable
+                // legacy stream must warn here instead of blocking Session creation.
+                let activeLegacy = 0;
+                try {
+                    // oxlint-disable-next-line typescript/no-deprecated -- Explicit warning for legacy Schedule history.
+                    activeLegacy = foldScheduleEvents(session.ownEvents()).active.length;
+                }
+                catch (error) {
+                    /* v8 ignore next -- foldScheduleEvents normalizes every rejected stream to ScheduleLogError. */
+                    if (!(error instanceof ScheduleLogError))
+                        throw error;
+                    ctx.logger.warn(`schedule: Session "${session.id}" historical events could not be read (${error.message}); the legacy reminder is ignored.`);
+                    return;
+                }
+                if (activeLegacy > 0) {
+                    ctx.logger.warn(`schedule: Session "${session.id}" contains legacy reminders; recreate active reminders with schedule_create.`);
+                }
+            }, { global: true });
+            // Host tasks outlive their Session's Agent, so archive admission reads the
+            // stored rows rather than a live runtime: an idle Session whose reminders
+            // are still armed refuses the archive, and an archiving stop deletes those
+            // rows instead of letting them deliver into a closed Session.
+            ctx.effect(() => {
+                const activity = ctx.on('workspace/session-activity', async ({ sessionId }, next) => {
+                    const active = await this.list({ sessionId });
+                    const rest = await next();
+                    if (active.length === 0)
+                        return rest;
+                    const own = {
+                        kind: 'schedule',
+                        items: active.map(record => ({ id: record.id, label: record.title })),
+                    };
+                    return [own, ...rest];
+                });
+                const stop = ctx.on('workspace/session-stop', async ({ sessionId }) => {
+                    await this.stopSessionTasks(sessionId);
+                });
+                return () => {
+                    stop();
+                    activity();
+                };
+            }, 'schedule.archiveAdmission()');
+        }
+        async [Service.init]() {
+            await this.initialized;
+        }
+        /**
+         * Create a reminder bound to the caller-selected Session without activating it.
+         *
+         * The request must supply a title; a missing, blank-after-trim, or over-long
+         * title rejects with `invalid_prompt` instead of deriving one from the prompt.
+         * The record is built from the clock reading taken before the request joins the
+         * serialized queue, so a create that waits behind a longer operation keeps its
+         * request-time anchor and may already be due when the queue reaches it.
+         * @param sessionId - Original Session receiving the reminder.
+         * @param request - Validated tool selector, required title, and reminder content.
+         * @param signal - Optional cancellation checked before persistence begins, including after FIFO waits.
+         * @returns The durably stored schedule. Cancellation does not roll back an in-flight write.
+         */
+        async create(sessionId, request, signal) {
+            if (Number(request.at !== undefined) + Number(request.after_seconds !== undefined)
+                + Number(request.every_seconds !== undefined) + Number(request.daily !== undefined)
+                + Number(request.weekly !== undefined) + Number(request.cron !== undefined) > 1) {
+                throw new ScheduleInputError('invalid_selector', 'Exactly one reminder selector is required.');
+            }
+            const title = scheduleTitle(request.title);
+            const id = ScheduleId(`schedule-${randomUUID()}`);
+            const now = Date.now();
+            let record;
+            if (request.at !== undefined) {
+                record = createAtScheduleRecord(id, request.prompt, request.at, now, title);
+            }
+            else if (request.after_seconds !== undefined) {
+                record = createAfterScheduleRecord(id, request.prompt, request.after_seconds, now, title);
+            }
+            else if (request.every_seconds !== undefined) {
+                record = createEveryScheduleRecord(id, request.prompt, request.every_seconds, now, title);
+            }
+            else if (request.daily !== undefined)
+                record = createDailyScheduleRecord(id, request.prompt, request.daily, now, title);
+            else if (request.weekly !== undefined)
+                record = createWeeklyScheduleRecord(id, request.prompt, request.weekly, now, title);
+            else if (request.cron !== undefined)
+                record = createCronScheduleRecord(id, request.prompt, request.cron, now, title);
+            else
+                throw new ScheduleInputError('invalid_selector', 'Exactly one reminder selector is required.');
+            return this.serialize(async () => {
+                const domain = await this.getDomain();
+                signal?.throwIfAborted();
+                await domain.table('tasks').put(id, {
+                    sessionId, record, status: 'active', deliveryHistory: { records: [], earlierRecordsUnavailable: false },
+                });
+                this.emitChanged();
+                this.runtime?.requestDrive();
+                return record;
+            });
+        }
+        /**
+         * Read the selected Session's active tasks without resuming its Agent.
+         * @param request - Session whose task list is requested.
+         * @returns Persisted reminders in storage order.
+         */
+        async list(request) {
+            const domain = await this.getDomain();
+            return [...domain.table('tasks').entries()]
+                .filter(([, task]) => task.sessionId === request.sessionId && task.status === 'active')
+                .map(([, task]) => task.record);
+        }
+        /**
+         * Read all active and inactive Host reminders with their original Session bindings.
+         * A deleted reminder has no row, so it is absent here.
+         * Does not activate Sessions or read Session history.
+         * @returns Reminders ordered by scheduledAt ascending, then lexicographically by id.
+         */
+        async catalog() {
+            const domain = await this.getDomain();
+            return [...domain.table('tasks').entries()]
+                .map(([, task]) => ({
+                ...task.record, sessionId: task.sessionId, status: task.status,
+                ...(task.lastDelivery === undefined ? {} : { lastDelivery: task.lastDelivery }),
+            }))
+                .sort((a, b) => a.scheduledAt.localeCompare(b.scheduledAt) || a.id.localeCompare(b.id));
+        }
+        /**
+         * Read saved inbox deliveries without activating or reading the original Session.
+         * The task's own row supplies its binding, so its records stay readable through this lookup.
+         * @param request - Session binding, task identity, explicit limit, and optional exclusive message cursor.
+         * @returns Newest-first deliveries in append order, or a task/cursor lookup failure.
+         * @throws ScheduleInputError when limit is not a safe integer from 1 through 100.
+         */
+        async history(request) {
+            if (!Number.isSafeInteger(request.limit) || request.limit < 1 || request.limit > 100) {
+                throw new ScheduleInputError('invalid_rule', 'Delivery history limit must be a safe integer from 1 through 100.');
+            }
+            const task = (await this.getDomain()).table('tasks').get(request.id);
+            if (task === undefined || task.sessionId !== request.sessionId) {
+                return { id: request.id, code: 'schedule_not_found' };
+            }
+            return deliveryHistoryPage(task, request, this.retention);
+        }
+        /**
+         * Delete one task belonging to the selected Session, leaving queued messages intact.
+         *
+         * The row is removed: the task no longer schedules, leaves `list` and `catalog`, and its
+         * saved delivery records go with it.
+         * @param request - Session and exact task identity.
+         * @param signal - Optional cancellation checked before persistence begins, including after FIFO waits.
+         * @returns Whether that Session owned a deleted task. Cancellation does not roll back an in-flight write.
+         */
+        async delete(request, signal) {
+            return this.serialize(async () => {
+                const tasks = (await this.getDomain()).table('tasks');
+                signal?.throwIfAborted();
+                const current = tasks.get(request.id);
+                if (current === undefined || current.sessionId !== request.sessionId) {
+                    return { id: request.id, deleted: false, code: 'schedule_not_found' };
+                }
+                await tasks.delete(request.id);
+                this.emitChanged();
+                this.runtime?.requestDrive();
+                return { id: request.id, deleted: true };
+            });
+        }
+        /**
+         * Update the name, instruction, and timing of an active task within the original Session
+         * binding without activating the Session or changing saved deliveries.
+         *
+         * Each supplied field replaces its stored value; an omitted field keeps it. A name or
+         * instruction change alone does not reset the committed target.
+         * @param request - Task binding, complete observed record, and any combination of timing, name, and instruction.
+         * @param signal - Cancellation checked after domain readiness and FIFO waits, before persistence begins.
+         * @returns The committed record, unchanged record for a no-op, or a non-mutating input/lookup/conflict result.
+         * Storage and lifecycle failures reject; cancellation after a write starts does not roll it back.
+         */
+        async update(request, signal) {
+            return this.serialize(async () => {
+                const tasks = (await this.getDomain()).table('tasks');
+                signal?.throwIfAborted();
+                const current = tasks.get(request.id);
+                if (current === undefined || current.sessionId !== request.sessionId) {
+                    return { id: request.id, updated: false, code: 'schedule_not_found' };
+                }
+                if (current.status === 'inactive')
+                    return { id: request.id, updated: false, code: 'schedule_ended' };
+                const result = resolveScheduleUpdate(current.record, request.expected, request.change, Date.now(), request);
+                if (!('record' in result) || !result.updated)
+                    return result;
+                await tasks.put(request.id, { ...current, record: result.record });
+                this.emitChanged();
+                this.runtime?.requestDrive();
+                return result;
+            });
+        }
+        /**
+         * Dispatch one post-commit `schedule/changed` notification, containing
+         * synchronous listener failures: every call site emits only after its durable
+         * task write landed, so a throwing listener must not reject the caller or
+         * skip the following `requestDrive()`.
+         */
+        emitChanged() {
+            try {
+                this.ctx.emit('schedule/changed');
+            }
+            catch (error) {
+                // Swallows synchronous observer exceptions only: emit dispatches
+                // listeners inline and nothing else runs in the try. The event is a
+                // notification, not a transaction participant.
+                this.ctx.logger.warn(`schedule: schedule/changed listener failed: ${String(error)}`);
+            }
+        }
+        async getDomain() {
+            await this.initialized;
+            return this.ready;
+        }
+        /**
+         * Remove every active task stored for one Session, inside the queue the tools
+         * use.
+         *
+         * Enumerating and deleting in one queue slot is what makes an archive stop
+         * ordered behind a create whose write is still in flight: a stop that read the
+         * table outside the queue could miss a row the create was about to commit and
+         * leave an armed reminder behind. Re-entering the public `delete()` from here
+         * would deadlock on this queue, so the rows are removed directly.
+         * @param sessionId - Session whose active Host tasks must stop.
+         */
+        async stopSessionTasks(sessionId) {
+            await this.serialize(async () => {
+                const tasks = (await this.getDomain()).table('tasks');
+                const active = [...tasks.entries()]
+                    .filter(([, task]) => task.sessionId === sessionId && task.status === 'active')
+                    .map(([, task]) => task.record.id);
+                if (active.length === 0)
+                    return;
+                // One row per write: the domain table has no batch delete, and each row is
+                // durable on its own, so a failure partway through leaves the rows already
+                // removed committed. Observers hear about that change before the failure
+                // reaches the caller, which still receives it.
+                let removed = false;
+                let failure;
+                for (const id of active) {
+                    try {
+                        await tasks.delete(id);
+                        removed = true;
+                    }
+                    catch (error) {
+                        // Every row is attempted: the archive has already landed, so a row this
+                        // stop skipped would stay armed in a Session whose runtime then refuses
+                        // its model steps. A rejection reason that carries no Error still has to
+                        // report a failure, so it is wrapped before the first one is kept.
+                        failure ??= error instanceof Error ? error : new Error(`schedule stop failed: ${String(error)}`);
+                    }
+                }
+                if (removed) {
+                    this.emitChanged();
+                    this.runtime?.requestDrive();
+                }
+                if (failure !== undefined)
+                    throw failure;
+            });
+        }
+        serialize(work) {
+            if (this.stopping)
+                return Promise.reject(new Error('Schedule service is stopping'));
+            const pending = this.chain.then(work);
+            this.chain = pending.catch(() => undefined); // Preserve FIFO progress after the caller receives the failure.
+            return pending;
+        }
+    };
+})();
+export { ScheduleService };
+export default ScheduleService;
+//# sourceMappingURL=index.js.map

package/lib/types/runtime.d.ts

@@ -0,0 +1,42 @@
+import type { ContextFormed } from '@qilin-agent/llm';
+declare module '@qilin-agent/llm' {
+    interface MessageSourceMap {
+        'schedule': {
+            kind: 'schedule';
+        } & ContextFormed;
+    }
+}
+import type { Context } from '@qilin-agent/kylin';
+import type { DeliveryRetentionBounds } from './types.ts';
+import type { ScheduleTask } from './storage.ts';
+/** Largest delay Node timers represent without clamping. */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/** Owns at most one timer across recomputations; delivery and management share the serialized operation. */
+export declare class ScheduleRuntime {
+    private readonly ctx;
+    private readonly tasks;
+    private readonly transact;
+    private readonly commit;
+    private readonly retention;
+    private timer;
+    private running;
+    private stopping;
+    private requested;
+    /**
+     * @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: Context, tasks: () => readonly ScheduleTask[], transact: (work: () => Promise<void>) => Promise<void>, commit: (task: ScheduleTask) => Promise<void>, retention: DeliveryRetentionBounds);
+    /**
+     * Recompute the nearest obligation after startup or a durable change.
+     * Dispatch failures are logged; refused admission does not retry automatically.
+     */
+    requestDrive(): void;
+    /** Stop the timer and drain an accepted delivery before storage closes. */
+    dispose(): Promise<void>;
+    private clearTimer;
+    private drive;
+}
+//# sourceMappingURL=runtime.d.ts.map