@qilin-agent/schedule 3.1.7 → 3.1.9

package/lib/types/index.d.ts

@@ -1,14 +1,25 @@
 import z from '@qilin-agent/schemastery';
 import { Context, Service } from '@qilin-agent/kylin';
+import type { Agent } from '@qilin-agent/agent';
 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';
+import { type SessionId } from '@qilin-agent/session';
+import type { ScheduleCatalogEntry, ScheduleCreateRequest, ScheduleDeleteInactiveResult, ScheduleDeliveryHistoryRequest, ScheduleDeliveryHistoryResult, ScheduleEditRequest, ScheduleEditResult, ScheduleListRequest, ScheduleListResult, ScheduleRunRequest, ScheduleRunResult, ScheduleViewRequest, ScheduleViewResult } from './types.ts';
+export type * from './client.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';
+export { formatScheduleLocalTime } from './domain.ts';
+export { MIN_EVERY_INTERVAL_SECONDS, MAX_TITLE_LENGTH, REQUIRED_TITLE_MESSAGE, ScheduleId, ScheduleInputError, ScheduleLogError, canonicalizeCronExpression, createAfterScheduleRecord, createAtScheduleRecord, createEveryScheduleRecord, createDailyScheduleRecord, createWeeklyScheduleRecord, createCronScheduleRecord, createRRuleScheduleRecord, decodeScheduleRecord, isRecurringScheduleRecord, normalizeWeekdays, parseCronInput, parseWeeklyInput, renderReminderFraming, renderRecurringReminderBatchFraming, resolveEveryOccurrence, resolveDailyOccurrence, resolveWeeklyOccurrence, resolveCronOccurrence, resolveRecurringOccurrence, scheduleTitle, weeklyTime, } from './domain.ts';
 declare module '@qilin-agent/kylin' {
+    interface Events {
+        /**
+         * Restore a reminder's Session through its embedding's owning controller.
+         * Call next() to use the Web Session controller.
+         * @param sessionId - Original Session receiving the reminder.
+         * @mode waterfall
+         */
+        'schedule/resolve-agent'(sessionId: SessionId, next: () => Promise<Agent>): Promise<Agent>;
+    }
     interface Context {
         /** Durable Host-wide reminder management. */
         schedule: ScheduleService;
@@ -26,95 +37,143 @@ export interface Config {
      * cap and the window wins, and the newest records survive.
      */
     deliveryHistoryRecords?: number;
+    /**
+     * Shortest spacing, in seconds, from the occurrence of one delivery to the next delivery of one task whose target
+     * creates a Session at every delivery; omission defaults to 60. Timed and manual deliveries both wait for it.
+     */
+    newSessionIntervalSeconds?: number;
 }
+/** Page size of a task list request that states none. */
+export declare const DEFAULT_LIST_LIMIT = 100;
+/** Largest page size of one task list request. */
+export declare const MAX_LIST_LIMIT = 500;
 /**
- * Shared management service; reads, deletion, and timing edits never activate a Session.
+ * Shared management service; reads and management writes never activate a Session, and only delivery creates or
+ * resumes one.
  *
- * `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.
+ * `sessionPersistence` supplies header-only target validation and the `session/flush`
+ * listener that acknowledges durable inbox delivery through `ctx.sessions.flush()`.
  */
 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;
+    /** Resolved retention and admission limits shared with the runtime that appends acknowledgments. */
+    private readonly limits;
     private readonly ready;
     private readonly initialized;
     private chain;
+    private notifications;
     private runtime;
+    private resolveWebAgent;
     private stopping;
     /**
      * @param ctx - Host services owning storage, dispatch, and Session restoration.
-     * @param config - Validated retention configuration for delivery history.
+     * @param config - Validated delivery-history retention and new-Session admission configuration.
      */
     constructor(ctx: Context, config: Config);
     [Service.init](): Promise<void>;
+    /** Read effective delivery limits without loading or activating a task.
+     * @returns The configured minimum spacing between deliveries that each create a Session, in seconds.
+     */
+    deliveryLimits(): {
+        readonly newSessionIntervalSeconds: number;
+    };
     /**
-     * Create a reminder bound to the caller-selected Session without activating it.
+     * Create one task with a Host-generated identity for a human Remote caller.
+     * @param request - Title, prompt, recurrence, and delivery destination.
+     * @param signal - Cancellation checked before the durable write begins, including after FIFO waits.
+     * @returns The stored task. Cancellation does not roll back an in-flight write.
+     */
+    remoteCreate(request: ScheduleCreateRequest, signal?: AbortSignal): Promise<ScheduleCatalogEntry>;
+    /**
+     * Create one task and record the acting Agent's Session as involved; the Remote form omits that Session.
      *
-     * 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.
-     * A Session a delegated child owns rejects with `subagent_session`, because delivery
-     * can never reach it: the child is one whose delegation depth is above zero.
-     * 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.
+     * The record is built from the clock reading taken before the request joins the serialized queue. A `session`
+     * target must exist and must not belong to a delegated child; a `new_once` target reserves its Session identity.
+     * @param request - Title, prompt, recurrence, and delivery destination.
+     * @param actorSessionId - Session of the acting Agent, or undefined for a human caller.
+     * @param signal - Cancellation checked before the durable write begins, including after FIFO waits.
+     * @returns The stored task. Cancellation does not roll back an in-flight write.
+     */
+    create(request: ScheduleCreateRequest, actorSessionId?: SessionId, signal?: AbortSignal): Promise<ScheduleCatalogEntry>;
+    /**
+     * Read one page of Host tasks without activating target Sessions.
+     * @param request - Optional activity filter, page size, and offset.
+     * @returns The requested page and total matching task count.
+     */
+    list(request?: ScheduleListRequest): Promise<ScheduleListResult>;
+    /**
+     * Remote form of the shared Host-wide list.
+     * @param request - Optional activity filter, page size, and offset.
+     * @returns The requested page and total matching task count.
+     */
+    remoteList(request: ScheduleListRequest): Promise<ScheduleListResult>;
+    /**
+     * Read every Host task without a page bound or Session activation.
+     * @returns All tasks, active first, with target and execution metadata.
      */
     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.
+     * Read one task without activating its target Sessions.
+     * @param request - Task identity.
+     * @returns The task, or a non-mutating miss.
+     */
+    view(request: ScheduleViewRequest): Promise<ScheduleViewResult>;
+    /**
+     * Read one page of saved deliveries without activating or reading a target Session.
+     * @param request - Task identity, explicit page size, and optional exclusive cursor.
+     * @returns Newest-first saved deliveries, or a task/cursor lookup failure.
      */
     history(request: ScheduleDeliveryHistoryRequest): Promise<ScheduleDeliveryHistoryResult>;
     /**
-     * Delete one task belonging to the selected Session, leaving queued messages intact.
+     * Remote form of the target-based {@link ScheduleService.history}; an invalid limit rejects with
+     * `schedule/input-invalid`.
+     * @param request - Task identity, explicit limit, and optional exclusive message cursor.
+     * @returns Newest-first deliveries in append order, or a task/cursor lookup failure.
+     */
+    remoteHistory(request: ScheduleDeliveryHistoryRequest): Promise<ScheduleDeliveryHistoryResult>;
+    /**
+     * Deliver one task now without consuming or moving its scheduled occurrence; an archived destination Session rejects
+     * with `schedule/target-archived`.
+     * @param request - Task identity.
+     * @param signal - Cancellation checked after entering the delivery transaction and before delivery.
+     * @returns Task state after Session persistence acknowledged the delivery, `schedule_execution_pending` while
+     * another execution of the task is queued, running, or inside its delivery floor, or a non-mutating miss.
+     */
+    run(request: ScheduleRunRequest, signal?: AbortSignal): Promise<ScheduleRunResult>;
+    /**
+     * Delete every ended Host task, leaving active tasks armed.
      *
-     * The row is removed: the task no longer schedules, leaves `list` and `catalog`, and its
-     * saved delivery records go with it. A task bound to a Session a delegated child owns
-     * stays deletable even though creation and timing edits refuse that binding, so a task
-     * stored before that rule existed remains removable.
-     * @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.
+     * Ended tasks never schedule another delivery, so the removal changes no pending
+     * target and no timer is recomputed. Rows are enumerated and removed in one FIFO
+     * slot, so a delivery ordered behind this call ends its task after the
+     * enumeration rather than during it. Each row is one durable write: a failure
+     * rejects with the rows removed so far gone and the remaining rows still
+     * stored.
+     * A successful nonempty removal emits `schedule/changed` without Agent notices.
+     * A rejected removal announces `schedule/changed` because it does not establish
+     * which rows landed, and clients then re-read the catalog.
+     * @returns Count of removed rows; zero when the Host held no ended task.
+     */
+    deleteInactive(): Promise<ScheduleDeleteInactiveResult>;
+    /**
+     * Update or delete one task for a human Remote caller; an invalid patch rejects with `schedule/input-invalid`.
+     * @param request - Task identity and one update or delete operation.
+     * @param signal - Cancellation checked before the durable write begins, including after FIFO waits.
+     * @returns The updated task, the deletion outcome, or a non-mutating miss or conflict.
+     */
+    remoteEdit(request: ScheduleEditRequest, signal?: AbortSignal): Promise<ScheduleEditResult>;
+    /**
+     * Update or delete one task and record the acting Agent's Session as involved; the Remote form omits that Session.
      *
-     * Each supplied field replaces its stored value; an omitted field keeps it. A name or
-     * instruction change alone does not reset the committed target. A Session a delegated
-     * child owns returns the non-mutating `subagent_session` result, so an edit cannot
-     * re-arm a task bound to a Session delivery can never reach, and the Web editor can
-     * explain the refusal through the ordinary result it already renders.
-     * @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/refusal result.
-     * Storage and lifecycle failures reject; cancellation after a write starts does not roll it back.
-     */
-    update(request: ScheduleUpdateRequest, signal?: AbortSignal): Promise<ScheduleUpdateResult>;
+     * An update applies every patch field in one write and recomputes the next occurrence when the rule changes or
+     * the task resumes. A supplied `expectedUpdatedAt` that differs from the stored value returns `schedule_conflict`.
+     * @param request - Task identity and one update or delete operation.
+     * @param actorSessionId - Session of the acting Agent, or undefined for a human caller.
+     * @param signal - Cancellation checked before the durable write begins, including after FIFO waits.
+     * @returns The updated task, the deletion outcome, or a non-mutating miss or conflict.
+     */
+    edit(request: ScheduleEditRequest, actorSessionId?: SessionId, signal?: AbortSignal): Promise<ScheduleEditResult>;
     /**
      * Dispatch one post-commit `schedule/changed` notification, containing
      * synchronous listener failures: every call site emits only after its durable
@@ -124,30 +183,59 @@ export declare class ScheduleService extends TypertRemoteService {
     private emitChanged;
     private getDomain;
     /**
-     * Refuse a Session no delivery can reach because a delegated child owns it.
+     * Resolve a requested destination without activating a Session.
      *
-     * Delivery resolves the bound Session through `ctx.sessionController.resolveAgent`,
-     * which rejects the live Agent of a delegated child; a stored task for such a Session
-     * would stay permanently overdue and retry on every drive. Both operations that can
-     * arm a delivery read that same fact here instead of restating it: a delegated child
-     * is one whose {@link delegationDepthOf} is above zero, the accounting the delegation
-     * cap itself enforces, which survives a cold resume through the persisted header.
-     * @param sessionId - Session the task would be bound to.
-     * @returns The stable refusal for a delegated child's Session, or undefined when the Session is eligible.
-     */
-    private reminderTargetRefusal;
-    /**
-     * Remove every active task stored for one Session, inside the queue the tools
+     * A `session` target must exist and must not belong to a delegated child: a live Agent answers through
+     * {@link delegationDepthOf}, and a stored Session answers through the delegation depth in its saved header.
+     * @param request - Requested destination.
+     * @param signal - Cancellation of the stored Session header read.
+     * @returns Stored destination; a `new_once` target reserves its Session identity here.
+     */
+    private resolveTarget;
+    /** Check arming prerequisites without activating a Session; repeated inside the mutation FIFO. */
+    private validateTarget;
+    /** New destinations require a provider before a task can be armed. */
+    private requireSessionCreation;
+    /** Every stored task as a catalog entry, in {@link compareEntries} order. */
+    private entries;
+    private entry;
+    /**
+     * Tell each involved Session's live Agent about one committed change, except the acting Session.
+     * A stored Session stays inactive; it reads the current task state when it next lists its tasks.
+     */
+    private notify;
+    /**
+     * Queue one change notice behind earlier notices without adding Session I/O to the management operation.
+     * Callers queue inside the serialized operation, so teardown, which drains that queue first, cannot overtake it.
+     */
+    private queueNotification;
+    /**
+     * Remove every active task that delivers to 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
+     * leave an armed reminder behind. Re-entering the public `edit()` from here
      * would deadlock on this queue, so the rows are removed directly.
      * @param sessionId - Session whose active Host tasks must stop.
      */
     private stopSessionTasks;
+    /**
+     * Remove rows one durable write each inside the current queue slot.
+     *
+     * This storage domain has no batch delete primitive, so a rejection part-way
+     * through leaves the earlier rows removed and the rest stored; the rejection
+     * still announces `schedule/changed` so observers re-read instead of trusting
+     * a stale catalog. Enumerating and deleting in one queue slot is what keeps a
+     * removal ordered behind a write that is still in flight. A rejection reason
+     * that carries no Error is wrapped with the operation label.
+     * @param ids - rows to remove.
+     * @param label - failure message prefix naming the operation that owned them.
+     * @param rearm - whether the rows were armed, so the pending timer must be recomputed.
+     * @returns the number of rows this call removed.
+     */
+    private removeRows;
     private serialize;
 }
 export default ScheduleService;