@code-yeongyu/senpi 2026.8.18 → 2026.8.19

package/dist/core/extensions/builtin/loop/scheduler.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Pure state machine behind the `/loop` extension.
+ *
+ * Everything time-related or timer-related is injected: a {@link LoopClock} supplies
+ * `now`, and a {@link LoopTimerPort} owns the single armed timeout per loop. This module
+ * performs NO I/O, never calls `setTimeout`/`Date.now`, and never persists anything
+ * itself — the caller mirrors {@link LoopScheduler.getState} into the sidecar store. That
+ * keeps every invariant below testable with a fake clock and zero real waiting.
+ *
+ * The load-bearing invariants:
+ * - At most ONE queued or running tick per loop. A fire that lands while one is in flight
+ *   sets `coalescedFirePending` instead of enqueuing a second delivery, so a sleeping
+ *   laptop or a long turn can never produce a tick storm.
+ * - `nextFireAt` is ALWAYS recomputed from `now`, never from the stale due time, so all
+ *   occurrences missed during sleep collapse into exactly one catch-up tick.
+ * - 7-day expiry from `createdAt` is checked at arm, fire, re-entry and restore, is never
+ *   extended by a new wakeup, and no tick fires at or after it.
+ * - At most {@link MAX_ACTIVE_LOOPS} active loops; a further creation returns a typed
+ *   rejection and leaves existing loops armed.
+ * - A dispatched-tick budget (default {@link DEFAULT_MAX_TICKS}) ends the loop with
+ *   `tick_budget_exhausted` so a forgotten fast loop cannot spend without bound.
+ * - Keepalive is a two-strike device on dynamic loops only, and a user abort PAUSES a
+ *   loop instead of ending it (and is never counted as a keepalive omission).
+ * - Shutdown SUSPENDS: every senpi shutdown reason leaves the session resumable, so there
+ *   is deliberately no `session_closed` terminal reason.
+ * - A provider/turn error is never terminal.
+ */
+import type { DeliveryId, EffectiveInterval, EpochMs, LoopEndReason, LoopId, LoopPayload, LoopState, RequestedInterval, WakeupId } from "./types.ts";
+/** Absolute lifetime of a loop, measured from `createdAt`. */
+export declare const LOOP_EXPIRY_MS: number;
+/** Hard cap on simultaneously active loops per session. */
+export declare const MAX_ACTIVE_LOOPS = 5;
+/** Fallback wakeup length when a dynamic iteration forgets to reschedule. */
+export declare const DEFAULT_KEEPALIVE_SECONDS = 1200;
+export declare const MIN_KEEPALIVE_SECONDS = 60;
+export declare const MAX_KEEPALIVE_SECONDS = 3600;
+export declare const KEEPALIVE_SECONDS_ENV = "SENPI_LOOP_KEEPALIVE_SECONDS";
+/** Dispatched-tick budget per loop. */
+export declare const DEFAULT_MAX_TICKS = 2000;
+export declare const MIN_MAX_TICKS = 1;
+export declare const MAX_TICKS_ENV = "SENPI_LOOP_MAX_TICKS";
+export interface LoopClock {
+    now(): EpochMs;
+}
+/**
+ * Owns the ONE live timeout per loop. Implementations must apply the generation-counter
+ * discipline of `cache-keepalive/index.ts`: re-arming a key replaces its previous
+ * callback, and a cancelled callback must never run.
+ */
+export interface LoopTimerPort {
+    arm(key: string, dueAt: EpochMs, callback: () => void): void;
+    cancel(key: string): void;
+    cancelAll(): void;
+}
+export interface LoopIdFactory {
+    loopId(): LoopId;
+    wakeupId(): WakeupId;
+    deliveryId(): DeliveryId;
+}
+export interface LoopSchedulerDeps {
+    readonly sessionId: string;
+    readonly clock: LoopClock;
+    readonly timers: LoopTimerPort;
+    readonly ids: LoopIdFactory;
+    /** Defaults to `process.env`; injected so tests never mutate the real environment. */
+    readonly env?: Record<string, string | undefined>;
+    /** Previously persisted state, e.g. on session start. */
+    readonly initialState?: LoopState;
+    /** Called after every state revision so the caller can persist it. */
+    readonly onStateChanged?: (state: LoopState) => void;
+    /**
+     * Invoked when an armed timer fires. The owner is expected to run the due decision AND its
+     * side effects (persist + dispatch). Without it the scheduler only advances its own state,
+     * which would deliver a loop's first tick and then silently never recur.
+     */
+    readonly onFire?: (loopId: LoopId) => void;
+}
+export interface CreateFixedRequest {
+    readonly originalArgs: string;
+    readonly reentryPrompt: string;
+    readonly payload: LoopPayload;
+    readonly requestedInterval: RequestedInterval;
+    readonly effectiveInterval: EffectiveInterval;
+    readonly cronExpression: string;
+    readonly intervalMs: number;
+}
+export interface CreateDynamicRequest {
+    readonly originalArgs: string;
+    readonly reentryPrompt: string;
+    readonly payload: LoopPayload;
+}
+/** One dispatchable delivery. The caller turns this into a message; ticks never steer. */
+export interface LoopTick {
+    readonly loopId: LoopId;
+    readonly deliveryId: DeliveryId;
+    /** Occurrence this delivery represents; equal to the `now` it was decided at. */
+    readonly scheduledForAt: EpochMs;
+    readonly deliverAs: "followUp";
+    /** True when this delivery drains a coalesced or recovered occurrence. */
+    readonly coalesced: boolean;
+}
+export type CreateRejectionReason = "active_loop_cap";
+export type CreateResult = {
+    readonly ok: true;
+    readonly loopId: LoopId;
+    readonly supersededLoopId?: LoopId;
+} | {
+    readonly ok: false;
+    readonly reason: CreateRejectionReason;
+    readonly cap: number;
+    readonly activeLoopIds: readonly LoopId[];
+    readonly message: string;
+};
+export type DueResult = {
+    readonly action: "dispatch";
+    readonly tick: LoopTick;
+} | {
+    readonly action: "coalesce";
+} | {
+    readonly action: "expire";
+};
+export type TickOutcome = "completed" | "error" | "retrying";
+export interface TickSettledInput {
+    readonly loopId: LoopId;
+    readonly deliveryId: DeliveryId;
+    readonly outcome: TickOutcome;
+}
+export type SettledResult = {
+    readonly action: "dispatch";
+    readonly tick: LoopTick;
+} | {
+    readonly action: "coalesce";
+} | {
+    readonly action: "expire";
+} | {
+    readonly action: "idle";
+} | {
+    readonly action: "in_progress";
+} | {
+    readonly action: "ended";
+    readonly endReason: LoopEndReason;
+} | {
+    readonly action: "ignored";
+};
+export interface ScheduleWakeupInput {
+    readonly loopId: LoopId;
+    /** Already clamped to `[60, 3600]` by the tool executor. */
+    readonly delaySeconds: number;
+    readonly requestedDelaySeconds: number;
+    readonly reason: string;
+    readonly prompt: string;
+    readonly noop: boolean;
+}
+export type ScheduleWakeupResult = {
+    readonly ok: true;
+    readonly wakeupId: WakeupId;
+    readonly replacedWakeupId?: WakeupId;
+    readonly dueAt: EpochMs;
+    readonly noopStreak: number;
+} | {
+    readonly ok: false;
+    readonly reason: "unknown_loop" | "not_dynamic" | "ended" | "expired";
+};
+export type KeepaliveResult = {
+    readonly action: "keepalive_armed";
+    readonly wakeupId: WakeupId;
+    readonly delaySeconds: number;
+    readonly dueAt: EpochMs;
+} | {
+    readonly action: "ended";
+    readonly endReason: "keepalive_exhausted" | "expired";
+} | {
+    readonly action: "ignored";
+};
+export interface AbortResult {
+    readonly action: "paused" | "ignored";
+}
+export interface TargetedResult {
+    readonly affectedLoopIds: readonly LoopId[];
+}
+export interface ShutdownResult {
+    readonly suspendedLoopIds: readonly LoopId[];
+}
+export interface RestoreOptions {
+    /**
+     * Loops the caller knows the user paused explicitly, which must stay paused instead of
+     * being re-armed. `phase: "suspended"` alone cannot express this: shutdown suspends too,
+     * and the persisted state has no field distinguishing the two. Omit it and every
+     * suspended loop is treated as shutdown-suspended and re-armed, per the plan's resume
+     * rule.
+     */
+    readonly userPausedLoopIds?: readonly LoopId[];
+}
+export interface RestoreResult {
+    readonly recoveryTicks: readonly LoopTick[];
+    readonly expiredLoopIds: readonly LoopId[];
+    readonly rearmedLoopIds: readonly LoopId[];
+    /** Loops left paused because {@link RestoreOptions.userPausedLoopIds} named them. */
+    readonly stillPausedLoopIds: readonly LoopId[];
+}
+export interface LoopScheduler {
+    getState(): LoopState;
+    /** State revisions applied so far; lets callers assert atomic multi-entry mutations. */
+    readonly mutationCount: number;
+    /** Effective dispatched-tick budget after the env override and the minimum of 1. */
+    readonly maxTicks: number;
+    /** Effective keepalive fallback length in seconds after clamping. */
+    readonly keepaliveSeconds: number;
+    /** Delivery id of the queued/running tick of a loop, when one is in flight. */
+    currentDeliveryId(loopId: LoopId): DeliveryId | undefined;
+    createFixed(request: CreateFixedRequest): CreateResult;
+    createDynamic(request: CreateDynamicRequest): CreateResult;
+    onDue(loopId: LoopId, nowMs: EpochMs, sessionBusy: boolean): DueResult;
+    onTickSettled(input: TickSettledInput): SettledResult;
+    onScheduleWakeup(request: ScheduleWakeupInput): ScheduleWakeupResult;
+    onTurnEndedWithoutSchedule(loopId: LoopId): KeepaliveResult;
+    onUserAbort(loopId: LoopId): AbortResult;
+    pause(target: LoopId | "all"): TargetedResult;
+    resume(target: LoopId | "all"): TargetedResult;
+    stop(target: LoopId | "all", detail: string): TargetedResult;
+    onShutdown(): ShutdownResult;
+    restore(nowMs: EpochMs, options?: RestoreOptions): RestoreResult;
+}
+export declare function createLoopScheduler(deps: LoopSchedulerDeps): LoopScheduler;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/core/extensions/builtin/loop/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/loop/scheduler.ts"],"names":[],"mappings":"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"}