@ours.network/fleet 1.2.0-nightly.68 → 1.2.0-nightly.69

package/dist/reminders/store.d.ts

@@ -21,6 +21,15 @@
  * 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;
@@ -70,6 +79,40 @@ export interface ReminderRecord {
     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;
@@ -84,6 +127,10 @@ export interface ReminderEvent {
     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;
@@ -99,6 +146,7 @@ export interface ScheduleInput {
     time_zone?: unknown;
     fold?: unknown;
     late_window_seconds?: unknown;
+    interrupt?: unknown;
 }
 export interface ReminderView {
     id: string;
@@ -113,6 +161,8 @@ export interface ReminderView {
     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;
@@ -122,6 +172,7 @@ export interface ReminderView {
         id: string;
         state: ReminderEventState;
         revision: number;
+        interrupt_state?: ReminderInterruptOutcome;
     };
 }
 export declare class ReminderStore {
@@ -168,6 +219,20 @@ export declare class ReminderStore {
     };
     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;
@@ -184,6 +249,20 @@ export declare class ReminderStore {
     };
     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;
@@ -221,6 +300,27 @@ export declare class ReminderStore {
         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

package/dist/reminders/store.js

@@ -26,6 +26,15 @@ import { ReminderScheduleError, resolveSchedule } from './schedule.js';
  * 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 const SELF_REMINDERS_FILE = '.self-reminders.json';
 export const MAX_OPEN_REMINDERS = 100;
@@ -37,6 +46,7 @@ const MAX_HORIZON_MS = 5 * 366 * 24 * 3600 * 1000;
 const MAX_TITLE_CHARS = 200;
 const MAX_NOTE_CHARS = 4000;
 const MAX_REQUEST_KEY_CHARS = 200;
+const INTERRUPT_OUTCOMES = new Set(['requested', 'cancelled', 'ended', 'forced', 'failed', 'unknown']);
 export class ReminderError extends Error {
     code;
     constructor(code, message) {
@@ -81,6 +91,13 @@ function revisionOf(raw) {
         throw new ReminderError('invalid_request', 'expected_revision must be the current positive revision');
     return raw;
 }
+function urgency(raw) {
+    if (raw === undefined || raw === null)
+        return false;
+    if (typeof raw !== 'boolean')
+        throw new ReminderError('invalid_request', 'interrupt must be true or false');
+    return raw;
+}
 export class ReminderStore {
     owner;
     now;
@@ -137,6 +154,10 @@ export class ReminderStore {
     recover() {
         const at = iso(this.now());
         for (const event of Object.values(this.state.events)) {
+            // An interruption requested by the previous process has an unknown end.
+            // Keep the mark (so it is never requested again) and say so.
+            if (event.interrupt?.outcome === 'requested')
+                event.interrupt = { ...event.interrupt, outcome: 'unknown', settledAt: at, reason: 'restarted_before_outcome' };
             if (event.state === 'admitting') {
                 // The release guard never ran, so the model never saw it.
                 event.state = 'pending';
@@ -186,6 +207,8 @@ export class ReminderStore {
         const retime = !previous || input.local_time !== undefined || input.time_zone !== undefined || input.fold !== undefined;
         const late = input.late_window_seconds === undefined && previous
             ? previous.lateWindowSeconds : lateWindow(input.late_window_seconds);
+        const interrupt = input.interrupt === undefined && previous
+            ? previous.interrupt === true : urgency(input.interrupt);
         let when;
         if (retime) {
             try {
@@ -205,7 +228,7 @@ export class ReminderStore {
         else {
             when = { localTime: previous.localTime, timeZone: previous.timeZone, fold: previous.fold, dueAt: Date.parse(previous.dueAt) };
         }
-        return { title, note, ...when, late };
+        return { title, note, ...when, late, interrupt };
     }
     openCount() {
         return Object.values(this.state.reminders).filter(item => item.state === 'active' || item.state === 'delivered').length;
@@ -216,6 +239,9 @@ export class ReminderStore {
             title: input.title ?? null, note: input.note ?? null, local_time: input.local_time ?? null,
             time_zone: input.time_zone ?? null, fold: input.fold ?? null,
             late_window_seconds: input.late_window_seconds ?? null,
+            // Only an explicit urgent request changes the digest, so a retry of a
+            // call made before `interrupt` existed (or with it false) still matches.
+            ...(input.interrupt === true ? { interrupt: true } : {}),
         });
         const existing = Object.values(this.state.reminders).find(item => item.requestKey === key);
         if (existing) {
@@ -234,6 +260,7 @@ export class ReminderStore {
                 ...(values.fold === undefined ? {} : { fold: values.fold }),
                 dueAt: iso(values.dueAt), lateWindowSeconds: values.late,
                 expiresAt: iso(values.dueAt + values.late * 1000), createdAt: at, updatedAt: at,
+                ...(values.interrupt ? { interrupt: true } : {}),
             };
             state.reminders[record.id] = record;
             this.prune(state);
@@ -264,6 +291,10 @@ export class ReminderStore {
                 delete target.fold;
             else
                 target.fold = values.fold;
+            if (values.interrupt)
+                target.interrupt = true;
+            else
+                delete target.interrupt;
             delete target.closedReason;
             return this.view(target);
         });
@@ -523,6 +554,80 @@ export class ReminderStore {
         }
         return { dispatch: true };
     }
+    /**
+     * 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) {
+        const event = this.state.events[eventId];
+        const record = event && this.state.reminders[event.reminderId];
+        return Boolean(event && record && record.interrupt === true && !event.interrupt
+            && (event.state === 'pending' || event.state === 'admitting')
+            && record.state === 'active' && record.revision === event.revision);
+    }
+    /**
+     * 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, target) {
+        if (!this.mayInterrupt(eventId) || this.state.events[eventId].state !== 'admitting')
+            return false;
+        if (!target.source || !target.promptId || !target.generation)
+            return false;
+        const event = this.state.events[eventId];
+        try {
+            this.commit(() => {
+                event.interrupt = {
+                    requestedAt: iso(this.now()), outcome: 'requested',
+                    target: {
+                        source: target.source, promptId: target.promptId, generation: target.generation,
+                        ...(target.sessionId ? { sessionId: target.sessionId } : {}),
+                    },
+                };
+                delete event.interruptDeferred;
+            });
+        }
+        catch {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * 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, reason) {
+        const event = this.state.events[eventId];
+        if (!event || event.interrupt || event.interruptDeferred === reason)
+            return;
+        try {
+            this.commit(() => { event.interruptDeferred = reason; });
+        }
+        catch { /* diagnostic only */ }
+    }
+    /** How the requested interruption ended. Diagnostic; never moves the event. */
+    recordInterruptOutcome(eventId, outcome, reason) {
+        const event = this.state.events[eventId];
+        if (!event?.interrupt || event.interrupt.outcome !== 'requested')
+            return;
+        try {
+            this.commit(() => {
+                event.interrupt = {
+                    ...event.interrupt, outcome, settledAt: iso(this.now()), ...(reason ? { reason } : {}),
+                };
+            });
+        }
+        catch { /* stays `requested`: still never re-requested, still not delivered */ }
+    }
+    /** Still the current, undispatched claim this process made? Re-checked after every await. */
+    stillAdmitting(eventId) {
+        const event = this.state.events[eventId];
+        const record = event && this.state.reminders[event.reminderId];
+        return Boolean(event && record && event.state === 'admitting' && record.state === 'active'
+            && record.revision === event.revision);
+    }
     /**
      * An admission that ended without the release guard dispatching it (queue
      * refused, session died, release refused while stopping) goes back to
@@ -576,10 +681,14 @@ export class ReminderStore {
             title: record.title, note: record.note,
             local_time: record.localTime, time_zone: record.timeZone,
             ...(record.fold === undefined ? {} : { fold: record.fold }),
-            due_at: record.dueAt, late_window_seconds: record.lateWindowSeconds, expires_at: record.expiresAt,
+            due_at: record.dueAt, late_window_seconds: record.lateWindowSeconds, interrupt: record.interrupt === true,
+            expires_at: record.expiresAt,
             created_at: record.createdAt, updated_at: record.updatedAt,
             ...(record.closedReason ? { closed_reason: record.closedReason } : {}),
-            ...(event ? { event: { id: event.id, state: event.state, revision: event.revision } } : {}),
+            ...(event ? { event: {
+                    id: event.id, state: event.state, revision: event.revision,
+                    ...(event.interrupt ? { interrupt_state: event.interrupt.outcome } : {}),
+                } } : {}),
         };
     }
     eventView(event) {
@@ -589,6 +698,18 @@ export class ReminderStore {
             ...(event.dispatchedAt ? { dispatched_at: event.dispatchedAt } : {}),
             ...(event.closedAt ? { closed_at: event.closedAt } : {}),
             ...(event.reason ? { reason: event.reason } : {}),
+            ...(event.interruptDeferred ? { interrupt_deferred: event.interruptDeferred } : {}),
+            ...(event.interrupt ? { interrupt: {
+                    state: event.interrupt.outcome, requested_at: event.interrupt.requestedAt,
+                    target_source: event.interrupt.target.source,
+                    target: {
+                        source: event.interrupt.target.source, prompt_id: event.interrupt.target.promptId,
+                        generation: event.interrupt.target.generation,
+                        ...(event.interrupt.target.sessionId ? { session_id: event.interrupt.target.sessionId } : {}),
+                    },
+                    ...(event.interrupt.settledAt ? { settled_at: event.interrupt.settledAt } : {}),
+                    ...(event.interrupt.reason ? { reason: event.interrupt.reason } : {}),
+                } } : {}),
         };
     }
 }
@@ -618,10 +739,16 @@ function validFile(value) {
     return Object.entries(file.reminders).every(([id, item]) => item && item.id === id
         && Number.isSafeInteger(item.revision) && item.revision >= 1 && reminderStates.has(item.state)
         && typeof item.requestKey === 'string' && typeof item.title === 'string' && typeof item.note === 'string'
-        && Number.isFinite(Date.parse(item.dueAt)) && Number.isFinite(Date.parse(item.expiresAt)))
+        && Number.isFinite(Date.parse(item.dueAt)) && Number.isFinite(Date.parse(item.expiresAt))
+        && (item.interrupt === undefined || item.interrupt === true))
         && Object.entries(file.events).every(([id, item]) => item && item.id === id
             && typeof item.reminderId === 'string' && Number.isSafeInteger(item.revision) && eventStates.has(item.state)
-            && Number.isSafeInteger(item.attempts));
+            && Number.isSafeInteger(item.attempts)
+            && (item.interrupt === undefined || (typeof item.interrupt === 'object' && item.interrupt !== null
+                && typeof item.interrupt.requestedAt === 'string' && typeof item.interrupt.target?.source === 'string'
+                && typeof item.interrupt.target.promptId === 'string' && typeof item.interrupt.target.generation === 'string'
+                && (item.interrupt.target.sessionId === undefined || typeof item.interrupt.target.sessionId === 'string')
+                && INTERRUPT_OUTCOMES.has(item.interrupt.outcome))));
 }
 /** Remove a retired agent's reminder store and any quarantined copies. */
 export function removeReminderState(stateDir) {

package/dist/reminders/tools.js

@@ -9,6 +9,10 @@ const schedule = {
     time_zone: z.string().describe('IANA zone the time is meant in, e.g. "Europe/London", "America/New_York" or "UTC". Use the zone of the person or task, not a guess.'),
     fold: z.union([z.literal(0), z.literal(1)]).optional().describe('Only for a wall time that occurs twice when clocks go back: 0 = first occurrence, 1 = second.'),
     late_window_seconds: z.number().int().optional().describe('How late the wake may still be delivered if this agent or the host was offline or busy at the due time (60..604800, default 3600). After it the reminder expires without a wake.'),
+    interrupt: z.boolean().optional().describe('Default false: the wake waits until you are idle. true only for a return that is genuinely time-bound: '
+        + 'when due and you are busy with interruptible work, Fleet asks your current turn to stop (session and context are kept) and wakes you with this reminder instead of waiting. '
+        + 'At most one interruption per reminder revision. It never pre-empts owner requests, the owner console, startup, a pending permission, queued work or another reminder; '
+        + 'then it waits like an ordinary reminder. Not a hard real-time alarm: no wake while the host or agent is down, and model start-up still takes time.'),
 };
 function result(value) {
     return {
@@ -90,6 +94,7 @@ admit) {
             time_zone: schedule.time_zone.optional(),
             fold: schedule.fold,
             late_window_seconds: schedule.late_window_seconds,
+            interrupt: schedule.interrupt,
         },
     }, async ({ id, expected_revision, ...changes }) => run(({ store }) => store.update(id, expected_revision, changes), true));
     server.registerTool('fleet_reminder_cancel', {
@@ -97,7 +102,8 @@ admit) {
         inputSchema: { id: z.string(), expected_revision: z.number().int() },
     }, async ({ id, expected_revision }) => run(({ store }) => store.cancel(id, expected_revision), true));
     server.registerTool('fleet_reminder_inspect', {
-        description: 'Read the reminder behind a [fleet-reminder] wake, including its note, and whether the wake is still current and eligible.',
+        description: 'Read the reminder behind a [fleet-reminder] wake, including its note, whether the wake is still current and eligible, '
+            + 'and for an urgent reminder what its interruption request did (interrupt.state).',
         inputSchema: { event_id: z.string() },
     }, async ({ event_id }) => run(({ store }) => store.inspect(event_id), false));
     server.registerTool('fleet_reminder_ack', {

package/dist/session/arbiter.d.ts

@@ -12,6 +12,42 @@ export type ReminderAttempt =
     error: string;
     admitted: false;
 };
+/**
+ * The single interruption an urgent reminder may request, as the arbiter saw
+ * it. `target` names the exact checked turn; `outcome` is what the session
+ * and the target's own terminal result actually reported.
+ */
+export interface UrgentInterruptReport {
+    target: UrgentInterruptTarget;
+    outcome: 'cancelled' | 'ended' | 'forced' | 'failed';
+    reason?: string;
+}
+export interface UrgentInterruptTarget {
+    source: NonNullable<SessionSnapshot['activePromptSource']>;
+    sessionId?: string;
+    generation: string;
+    promptId: string;
+}
+/** The urgent path's durable seams; every one is synchronous and owned by the reminder store. */
+export interface UrgentReminderHooks {
+    /** The durable `admitting` claim (as for `tryReminder`). False: nothing is queued. */
+    beforeQueue(): boolean;
+    /** Release fence; the only way the prompt reaches the model. */
+    releaseGuard(): boolean;
+    /** Whether this event may still request its one interruption. */
+    mayInterrupt(): boolean;
+    /** Durable mark written BEFORE the session is asked to cancel. False: do not cancel. */
+    markRequested(target: UrgentInterruptTarget): boolean;
+    /** How the requested interruption ended. */
+    recordOutcome(report: UrgentInterruptReport): void;
+    /** The busy turn was not interruptible this time, and why. */
+    deferred(reason: UrgentDeferral): void;
+    /** Still this caller's current, undispatched claim? Re-checked after every await. */
+    stillAdmitting(): boolean;
+    /** The wake text, built once the interruption (if any) is known. */
+    text(report?: UrgentInterruptReport): string;
+}
+export type UrgentDeferral = 'protected_turn' | 'untracked_turn' | 'permission_pending' | 'queued_work' | 'session_starting' | 'interrupt_unsupported' | 'uncorrelatable' | 'interrupt_already_used';
 export type ScheduledAttempt = {
     state: 'started';
     queued: QueuedPrompt;
@@ -34,6 +70,10 @@ export declare class RoleTurnArbiter implements AgentSession {
     readonly capabilities: import("./types.js").AgentSessionCapabilities | undefined;
     private tail;
     private unsettled;
+    /** Admissions waiting for the boundary; an urgent interruption yields to them. */
+    private waiting;
+    /** Terminal results of prompts this arbiter admitted and that have not settled yet. */
+    private readonly live;
     private stopping;
     private retiring;
     /** Bumped by `retireStalledAdmission`; every claim carries the one it was made under. */
@@ -91,6 +131,26 @@ export declare class RoleTurnArbiter implements AgentSession {
     tryReminder(text: string, origin: Extract<PromptOrigin, {
         kind: 'self-reminder';
     }>, beforeQueue: () => boolean, releaseGuard: () => boolean): Promise<ReminderAttempt>;
+    /**
+     * Admit an URGENT self-reminder wake. Idle: exactly `tryReminder`. Busy: the
+     * reminder may ask the exact checked turn to stop — once per event — and is
+     * then admitted at the next boundary like any other reminder.
+     *
+     * The check and the cancel request happen in one synchronous step inside the
+     * admission boundary, so the turn asked to stop is the turn that was checked.
+     * Only a running, correlatable, interruptible turn with nothing queued behind
+     * it and no admission waiting is ever asked to stop; anything else is a
+     * reported deferral (`busy`). After the cancellation the boundary is given up
+     * before the wake is queued, so an owner prompt (or any producer) that
+     * arrived meanwhile is admitted first and the wake simply finds the role
+     * busy. A forced, failed or uncertain cancellation never queues the wake.
+     */
+    tryUrgentReminder(origin: Extract<PromptOrigin, {
+        kind: 'self-reminder';
+    }>, hooks: UrgentReminderHooks): Promise<ReminderAttempt>;
+    /** The exact interruptible turn, or why there is none. Synchronous by design. */
+    private urgentTarget;
+    private queueReminder;
     /** Retire only at the same admission boundary used by all prompt producers. */
     retireIfIdle(expired: (snapshot: SessionSnapshot, queueDepth: number) => boolean): Promise<boolean>;
     sharedTurnId(promptId: string): string | undefined;