@ours.network/fleet 1.2.0-nightly.7 → 1.2.0-nightly.71

package/dist/reminders/store.d.ts

@@ -0,0 +1,341 @@
+/**
+ * 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.
+ *
+ * Urgency is an explicit opt-in per reminder (`interrupt`). Absent means false,
+ * so stores written before it existed keep their exact idle-only meaning, and
+ * an older runtime that ignores the field stays idle-only. An urgent event may
+ * request at most ONE interruption of the agent's current turn per revision:
+ * the request is durably recorded before the session is asked to cancel, so a
+ * crash, a forced adapter restart or a second urgent reminder can never turn
+ * it into a cancellation loop. Every later admission of that event is
+ * idle-only, and only the release guard ever records `dispatched`.
+ */
+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;
+    /** Present (true) only for an urgent reminder; absent is the idle-only default. */
+    interrupt?: true;
+}
+/**
+ * What became of an urgent event's single interruption request. `requested` is
+ * the durable mark written before the session is asked to cancel; it is never
+ * evidence that anything was cancelled or delivered.
+ *
+ * - `cancelled`: the target turn's own terminal result says it was cancelled
+ *   by this request (correlated, not inferred).
+ * - `ended`: the session reported the cancellation settled, but the target's
+ *   terminal could not be correlated, or it ended some other way.
+ * - `forced`: the adapter ignored the cancel and was restarted.
+ * - `failed`: the control call failed; it may or may not have reached the adapter.
+ * - `unknown`: the supervisor restarted before the outcome was recorded.
+ */
+export type ReminderInterruptOutcome = 'requested' | 'cancelled' | 'ended' | 'forced' | 'failed' | 'unknown';
+/**
+ * The exact turn an urgent event asked to stop: typed provenance and the
+ * session's own identifiers for it (prompt id within that session generation),
+ * never a body.
+ */
+export interface ReminderInterruptTarget {
+    source: string;
+    promptId: string;
+    generation: string;
+    sessionId?: string;
+}
+export interface ReminderEventInterrupt {
+    requestedAt: string;
+    target: ReminderInterruptTarget;
+    outcome: ReminderInterruptOutcome;
+    settledAt?: string;
+    reason?: 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;
+    /** The one interruption an urgent event may have requested. */
+    interrupt?: ReminderEventInterrupt;
+    /** Why an urgent event last found the busy turn not interruptible (diagnostic). */
+    interruptDeferred?: 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;
+    interrupt?: 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;
+    /** True only when this reminder may interrupt a busy turn when due. */
+    interrupt: boolean;
+    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;
+        interrupt_state?: ReminderInterruptOutcome;
+    };
+}
+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: {
+            interrupt?: {
+                reason?: string | undefined;
+                settled_at?: string | undefined;
+                state: ReminderInterruptOutcome;
+                requested_at: string;
+                target_source: string;
+                target: {
+                    session_id?: string | undefined;
+                    source: string;
+                    prompt_id: string;
+                    generation: string;
+                };
+            } | undefined;
+            interrupt_deferred?: string | undefined;
+            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: {
+            interrupt?: {
+                reason?: string | undefined;
+                settled_at?: string | undefined;
+                state: ReminderInterruptOutcome;
+                requested_at: string;
+                target_source: string;
+                target: {
+                    session_id?: string | undefined;
+                    source: string;
+                    prompt_id: string;
+                    generation: string;
+                };
+            } | undefined;
+            interrupt_deferred?: string | undefined;
+            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;
+    };
+    /**
+     * Whether this undispatched event may still ask to interrupt a busy turn: its
+     * reminder is urgent and current, and no interruption was ever requested
+     * for it (in this process or before a restart).
+     */
+    mayInterrupt(eventId: string): boolean;
+    /**
+     * Durable mark made BEFORE the session is asked to cancel. False: do not
+     * interrupt. Once written it is never cleared, which is what bounds every
+     * urgent event to one interruption.
+     */
+    markInterruptRequested(eventId: string, target: ReminderInterruptTarget): boolean;
+    /**
+     * Record why an urgent event did not interrupt this time. Written only when
+     * the reason changes, so a long busy stretch costs one write, not one per poll.
+     */
+    recordInterruptDeferred(eventId: string, reason: string): void;
+    /** How the requested interruption ended. Diagnostic; never moves the event. */
+    recordInterruptOutcome(eventId: string, outcome: Exclude<ReminderInterruptOutcome, 'requested'>, reason?: string): void;
+    /** Still the current, undispatched claim this process made? Re-checked after every await. */
+    stillAdmitting(eventId: string): boolean;
+    /**
+     * 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;