@ours.network/fleet 1.2.0-nightly.64 → 1.2.0-nightly.66

package/dist/reminders/store.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Durable, private, single-writer state for one agent's self-reminders.
+ *
+ * The runner that supervises the agent is the only writer: the agent's MCP
+ * tools, the dispatch timer and the session's release guard all run in that
+ * one process, and every mutation here is synchronous, so each method call is
+ * its own linearization point. Asynchronous callers (a queue receipt, a turn
+ * completion) never carry state across an `await`; they re-read the current
+ * record and apply only forward transitions, so a late receipt can never undo
+ * an acknowledgement, update or cancellation that happened meanwhile.
+ *
+ * Event lifecycle — the boundary that matters is `dispatched`:
+ *
+ *   pending ──admit──▶ admitting ──release guard──▶ dispatched ──ack──▶ acknowledged
+ *      ▲                   │                            │
+ *      └── not released ───┘                            └─ restart ─▶ uncertain (held)
+ *
+ * `dispatched` is written durably by the session's release guard immediately
+ * before the prompt is handed to the model. An event found `admitting` after a
+ * restart therefore provably never reached the model (reminder prompt bodies
+ * are not retained, so session recovery cannot replay them) and is retried
+ * under the same event id. An event found `dispatched` may or may not have been
+ * seen, so it is held as `uncertain` and never automatically re-admitted.
+ */
+export declare const SELF_REMINDERS_FILE = ".self-reminders.json";
+export declare const MAX_OPEN_REMINDERS = 100;
+export declare const MAX_RETAINED_CLOSED = 200;
+export declare const DEFAULT_LATE_WINDOW_SECONDS = 3600;
+export declare const MAX_LATE_WINDOW_SECONDS: number;
+export declare const MIN_LATE_WINDOW_SECONDS = 60;
+export type ReminderState = 'active' | 'delivered' | 'acknowledged' | 'cancelled' | 'expired';
+export type ReminderEventState = 'pending' | 'admitting' | 'dispatched' | 'uncertain' | 'acknowledged' | 'invalidated' | 'expired';
+/**
+ * Who a store belongs to. The fields that must match depend on lifetime,
+ * because that is what each lifetime keeps stable across its ordinary
+ * stop/start:
+ *
+ * - `permanent`: an orderly stop releases the managed runtime, and the next
+ *   start provisions a new runtime instance and action for the SAME identity
+ *   and state directory. Ownership is the role plus its identity CID. A
+ *   removed agent's state directory is deleted, so a later same-named agent
+ *   starts without this store; a replaced identity has a different CID.
+ * - `temporary` (including task members): suspend/resume keeps the runtime
+ *   instance and action, and retirement archives the directory with this store
+ *   removed. Ownership is role, CID, instance and action.
+ */
+export interface ReminderOwner {
+    role: string;
+    lifetime: 'permanent' | 'temporary';
+    /** Logical managed-runtime instance. */
+    instance: string;
+    cid: string;
+    /** Creation action of that runtime instance. */
+    action: string;
+}
+export interface ReminderRecord {
+    id: string;
+    requestKey: string;
+    requestDigest: string;
+    revision: number;
+    state: ReminderState;
+    title: string;
+    note: string;
+    localTime: string;
+    timeZone: string;
+    fold?: 0 | 1;
+    dueAt: string;
+    lateWindowSeconds: number;
+    expiresAt: string;
+    createdAt: string;
+    updatedAt: string;
+    closedReason?: string;
+}
+export interface ReminderEvent {
+    id: string;
+    reminderId: string;
+    revision: number;
+    state: ReminderEventState;
+    createdAt: string;
+    attempts: number;
+    retryAt?: string;
+    promptId?: string;
+    admittedAt?: string;
+    dispatchedAt?: string;
+    closedAt?: string;
+    reason?: string;
+}
+export declare class ReminderError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface ReminderWriter {
+    (path: string, contents: string): void;
+}
+export interface ScheduleInput {
+    title?: unknown;
+    note?: unknown;
+    local_time?: unknown;
+    time_zone?: unknown;
+    fold?: unknown;
+    late_window_seconds?: unknown;
+}
+export interface ReminderView {
+    id: string;
+    /** The caller's own idempotency key, so a retried or interrupted run can find its work. */
+    request_key: string;
+    revision: number;
+    state: ReminderState;
+    title: string;
+    note: string;
+    local_time: string;
+    time_zone: string;
+    fold?: 0 | 1;
+    due_at: string;
+    late_window_seconds: number;
+    expires_at: string;
+    created_at: string;
+    updated_at: string;
+    closed_reason?: string;
+    /** The current revision's wake, if one exists. */
+    event?: {
+        id: string;
+        state: ReminderEventState;
+        revision: number;
+    };
+}
+export declare class ReminderStore {
+    readonly owner: ReminderOwner;
+    private readonly now;
+    private readonly log;
+    private readonly write;
+    readonly path: string;
+    private state;
+    /**
+     * Load or create the store for exactly this owner (see `ReminderOwner`). A
+     * store written for anyone else is never adopted: it is moved aside and
+     * nothing in it is delivered, so a same-named successor or a replaced
+     * identity cannot inherit a predecessor's wakes.
+     */
+    constructor(stateDir: string, owner: ReminderOwner, now: () => number, log?: (line: string) => void, write?: ReminderWriter);
+    /** Restart recovery. Never re-admits anything that may have reached the model. */
+    private recover;
+    private persist;
+    /**
+     * Apply a mutation and persist it as one step. If the write fails the
+     * in-memory state is restored, so memory never claims what disk does not.
+     */
+    private commit;
+    private reminder;
+    private event;
+    private schedule;
+    private openCount;
+    create(requestKey: unknown, input: ScheduleInput): {
+        reminder: ReminderView;
+        created: boolean;
+    };
+    update(id: unknown, expectedRevision: unknown, input: ScheduleInput): ReminderView;
+    cancel(id: unknown, expectedRevision: unknown): ReminderView;
+    list(filter?: {
+        state?: unknown;
+        limit?: unknown;
+        after?: unknown;
+    }): {
+        uncertain_events: number;
+        after?: string | undefined;
+        reminders: ReminderView[];
+        more: boolean;
+    };
+    inspect(eventId: unknown): {
+        event: {
+            reason?: string | undefined;
+            closed_at?: string | undefined;
+            dispatched_at?: string | undefined;
+            id: string;
+            reminder_id: string;
+            revision: number;
+            state: ReminderEventState;
+            created_at: string;
+        };
+        reminder: ReminderView | undefined;
+        current: boolean;
+        eligible: boolean;
+        late_by_ms: number | undefined;
+    };
+    ack(eventId: unknown, expectedRevision: unknown): {
+        event: {
+            reason?: string | undefined;
+            closed_at?: string | undefined;
+            dispatched_at?: string | undefined;
+            id: string;
+            reminder_id: string;
+            revision: number;
+            state: ReminderEventState;
+            created_at: string;
+        };
+        acknowledged: boolean;
+        duplicate: boolean;
+    };
+    /**
+     * Earliest instant the dispatcher has work, or undefined when idle.
+     * `live` names admissions still owned by a queued prompt in this process:
+     * their own completion re-arms the dispatcher, so they are not work here.
+     */
+    nextWorkAt(live?: ReadonlySet<string>): number | undefined;
+    private openEvent;
+    /**
+     * Expire what is past its window and create a pending event for each due
+     * reminder. Returns the events ready to admit now, earliest due first.
+     */
+    sweep(live?: ReadonlySet<string>): ReminderEvent[];
+    /** Durable claim made before the prompt is queued. False: do not queue. */
+    markAdmitting(eventId: string): boolean;
+    /** Record the session's queue receipt; never moves an event backwards. */
+    recordReceipt(eventId: string, promptId: string): void;
+    /**
+     * The release guard: called synchronously by the session at the moment the
+     * prompt would be handed to the model. It returns true only after
+     * `dispatched` is durably on disk; any doubt refuses the dispatch.
+     */
+    claimDispatch(eventId: string, stopping: boolean): {
+        dispatch: boolean;
+        reason?: string;
+    };
+    /**
+     * An admission that ended without the release guard dispatching it (queue
+     * refused, session died, release refused while stopping) goes back to
+     * pending. Anything already past `admitting` is left exactly as it is.
+     */
+    releaseUndispatched(eventId: string, retryAt: number): void;
+    eventSummary(eventId: string): {
+        event: ReminderEvent;
+        reminder: ReminderRecord;
+    } | undefined;
+    private supersedeEvents;
+    /** Bound retained history; open reminders and their events are never dropped. */
+    private prune;
+    private view;
+    private eventView;
+}
+/** Remove a retired agent's reminder store and any quarantined copies. */
+export declare function removeReminderState(stateDir: string): void;