@tinycloud/courier 0.2.0-beta.37 → 0.2.0-beta.39

package/dist/watch.d.ts

@@ -2,6 +2,7 @@ import type { HookSubscription } from '@tinycloud/node-sdk';
 import type { StoredPeer } from './profile.js';
 import { type KV } from './inbox.js';
 import type { WakeApproval, WakeMessage, Waker, WatchLog } from './wake.js';
+import { type Notice, type Notifier } from './notify.js';
 export interface PendingWake {
     peer: string;
     threadId: string;
@@ -12,6 +13,38 @@ export interface PendingWake {
     firstSeenAt: number;
     lastSeenAt: number;
 }
+interface NoticeRetry {
+    /** Six digits while dispatching, otherwise six dashes; independent of the display count. */
+    dispatchArrivals: string;
+    tries: number;
+    nextAttemptAt: number;
+    logged: boolean;
+}
+type NeedsKind = 'message' | 'approval';
+interface NeedsSlot extends NoticeRetry {
+    threadId: string;
+    eventId: string;
+    count: string;
+    firstSeenAt: string;
+    arrivalFirstSeenAt: string;
+}
+interface PauseEpisode extends NoticeRetry {
+    kind: '' | 'paused' | 'peer-paused';
+    eventId: string;
+    /** Fixed-width saturating count of additional transitions represented by this slot. */
+    repeats: string;
+}
+/** Allocated only from our own thread/wake/pause records, never from incoming notice ids. */
+interface ThreadNoticeState {
+    ourPaused: boolean;
+    peerPaused: boolean;
+    lastPeerNoticeId: string;
+    lastNoticeSentAt: string;
+    ourMarkerId: string;
+    episodes: [PauseEpisode, PauseEpisode];
+    informPending: boolean;
+    informText: string;
+}
 export interface WatchState {
     v: 1;
     /** Keyed `<peer>/<threadId>`. */
@@ -19,11 +52,61 @@ export interface WatchState {
     /** Recently woken message ids, so a receipt write that failed cannot cause a second wake. */
     woken: string[];
     approvalsSeen: string[];
+    /** Message wake attempts today (UTC), per `<peer>/<threadId>`, as epoch ms (approval wakes do not count). */
+    wakes: Record<string, number[]>;
+    /** Threads this watcher has seen paused; a marker that vanishes from this list means the human resumed it. */
+    paused: string[];
+    /** Failed wake count and completion-based backoff, retained across watcher restarts. */
+    wakeRetries: Record<string, {
+        failures: number;
+        nextAttemptAt: number;
+    }>;
+    approvalRetries: Record<string, {
+        failures: number;
+        nextAttemptAt: number;
+    }>;
+    /** Posts and notifications that must happen exactly-ish once and survive a restart (retried until they succeed). */
+    outbox: OutboxItem[];
+    held: Record<string, HeldBacklog>;
+    /** One fixed record per locally known thread. Peer ids are values, never keys. */
+    threadNotices: Record<string, ThreadNoticeState>;
+    /** Two coalescing needs-you slots per locally paired peer, allocated only from local configuration. */
+    peerNotices: Record<string, Record<NeedsKind, NeedsSlot>>;
+    noticeGlobalLog: number[];
+    /** Every dispatch attempt, success or failure, per peer for the shared rolling-hour cap. */
+    noticeLog: Record<string, number[]>;
+}
+/** `tries`: notification dispatch attempts (max 3), or failed inform attempts (max 8). */
+export type OutboxItem = {
+    id: string;
+    kind: 'inform';
+    peer: string;
+    threadId: string;
+    text: string;
+    pauseId?: string;
+    tries?: number;
+    nextAttemptAt?: number;
+} | {
+    id: string;
+    kind: 'notify';
+    notice: Notice;
+    tries?: number;
+    nextAttemptAt?: number;
+    logged?: boolean;
+};
+/** Messages that arrived while a thread was paused; they wake the agent once, together, after `courier resume`. */
+export interface HeldBacklog {
+    peer: string;
+    threadId: string;
+    subject: string;
+    messages: WakeMessage[];
 }
 export interface WatchOptions {
     debounceMs: number;
     pollMs: number;
     ticketSeconds: number;
+    /** Spec §8: at most this many wakes per side per thread per 24 h, then the thread pauses. */
+    wakeBudget: number;
 }
 export declare const WATCH_DEFAULTS: WatchOptions;
 interface HookEventLike {
@@ -48,6 +131,14 @@ export interface WatchDeps {
     kvFor(peer: StoredPeer): Promise<KV>;
     wake: Waker;
     log: WatchLog;
+    /** Posts the `thread-paused` inform to a peer (own space, `to/<peer>/threads/<id>/msg/`). Default: nothing. */
+    postInform?(peer: string, threadId: string, text: string, pauseId?: string): Promise<void>;
+    /** Tells this side's human without a model (desktop notification or operator command). Default: log only. */
+    notify?: Notifier;
+    /** Local bounded notification log; omitted by library callers that want no disk output. */
+    notificationHome?: string;
+    /** D mode mirrors and receipts, then notifies without invoking a wake adapter. */
+    notifyOnly?: boolean;
     /**
      * Who this watcher is, for wake claims. `profileId` is stable for this profile on this machine (a restart keeps it,
      * a second profile or machine differs); `pid` and `isAlive` tell a restarted watcher its predecessor is dead.
@@ -71,6 +162,11 @@ export declare class Watcher {
     private readonly retryAt;
     private readonly waking;
     private approvalsRunning;
+    /** Thread keys currently paused: markers under me/state/paused/ plus those this watcher just wrote. */
+    private pausedKeys;
+    /** Serialises everything that reads or writes pause markers, so a stale listing cannot drop a pause just written. */
+    private pausedLock;
+    private readonly outboxBusy;
     private approvalsAgain;
     /** Unique to this run: a claim with this id is this process's own. */
     private readonly runId;
@@ -120,6 +216,8 @@ export declare class Watcher {
     /** Serialises syncs per peer; a request that arrives mid-sync reruns once after it. */
     sync(peer: StoredPeer, via: Via): Promise<void>;
     private syncPeer;
+    /** Only locally authored meta/messages/tasks, or a local wake/pause witness, establish a known thread. */
+    private syncKnownThreads;
     private mirrorCreate;
     /**
      * meta.json is immutable (create-only); tasks are mutable, so copy the latest until they are terminal. Runs after
@@ -137,7 +235,43 @@ export declare class Watcher {
     private approvalWake;
     /** Wake every thread whose debounce has elapsed (`force`: all of them now). Threads wake in parallel, one wake per thread at a time. */
     tick(force?: boolean): Promise<void>;
+    /** Spec §8: the budget is per side, per thread, per day. A day is the UTC calendar day, so it is easy to state and to check. */
+    private recentWakes;
     private wakeThread;
+    /** Budget reached: pause this side's wakes for the thread, tell the peer (inform), tell this side's human. */
+    private pauseThread;
+    private exclusive;
+    /** Called inside `mutate`: parks a message that arrived while its thread is paused (bounded). */
+    private hold;
+    /** Two episode values per known thread. Additional transitions coalesce, without allocating another slot. */
+    private queueEpisode;
+    /** Only the paired handles in our local configuration allocate needs-you state. */
+    private syncNoticePeers;
+    /** Bounded values only: a later delivery updates the same paired-peer slot. Called inside mutate. */
+    private queueNeeds;
+    private noticeSlot;
+    private rememberNotice;
+    /** Earliest rolling-hour retry under the global allowance and each paired peer's share. */
+    private noticeRateDeadline;
+    /** -1 appends; a nonnegative index yields that place; undefined leaves the pending slot alone. */
+    private admissionIndex;
+    /** Queue places can yield; the two fixed episode records retain all retry metadata. */
+    private enqueue;
+    private outboxCandidates;
+    /** Admit local work first, allowing eligible peers to pass deferred entries in a full queue. */
+    private fillOutbox;
+    private fairOutbox;
+    /** Completion matches both the fixed slot and episode ULID; another queued episode is independent. */
+    private finishOutbox;
+    /**
+     * Markers under me/state/paused/ are the truth. A marker that disappeared means the human resumed: the budget starts
+     * over and what arrived meanwhile wakes the agent once. Serialised, so overlapping calls never apply a stale listing.
+     */
+    syncPaused(): Promise<void>;
+    /** State that only matters for a day or an hour is dropped, so it cannot grow without bound. */
+    private pruneState;
+    /** Informs and notifications queued in state; failures back off (1, 2, 4 ... 15 minutes) and give up after 3 notification attempts or 8 inform failures. */
+    private runOutbox;
     pollOnce(via: Via): Promise<void>;
     /**
      * Runs until `signal` aborts. With `once`, does one catch-up and wakes everything immediately. Throws