@burdenoff/fe-libs 2026.1024.3 → 2026.1024.4

package/dist/shared/assistant/avatar/live/liveAvatarController.d.ts

@@ -4,7 +4,7 @@ import { AvatarMeterHandle } from './avatarAudioMeter';
 import { AvatarRoom, AvatarScheduler } from './avatarPorts';
 import { AvatarTrackerConfig } from './avatarPlaybackTracker';
 import { AvatarDecodedPiece, AvatarNotice, AvatarReplyOutputs } from './avatarReplyOutputs';
-import { AvatarBudgetScope, AvatarClientEndReason, AvatarSessionClient } from './avatarSessionClient';
+import { AvatarBudgetScope, AvatarClientEndReason, AvatarMinutes, AvatarMinutesReason, AvatarSessionClient, AvatarSessionMinutes } from './avatarSessionClient';
 import { AvatarReadinessProbeOptions } from './avatarTransport';
 /** End after this long without a reply on the avatar while it is on (OD8, BACKEND-DESIGN §8.7). */
 export declare const LIVE_AVATAR_IDLE_MS = 120000;
@@ -14,6 +14,20 @@ export declare const LIVE_AVATAR_END_BEFORE_DEADLINE_MS = 10000;
 export declare const LIVE_AVATAR_REQUEST_TIMEOUT_MS = 8000;
 /** The longest a connect may take (the avatar's own wait for its video, 8 s, plus the readiness probe, 6 s, plus slack). */
 export declare const LIVE_AVATAR_CONNECT_TIMEOUT_MS = 20000;
+/**
+ * ★ BOFF-9446: quiet minutes questions are at least this far apart, counted from the last availability question of any kind; one asked
+ * sooner waits for it. The check after a purchase keeps its own bounded pace (`LIVE_AVATAR_PURCHASE_POLL_MS`).
+ */
+export declare const LIVE_AVATAR_MINUTES_REFRESH_MS = 15000;
+/** ★ BOFF-9446: a quiet minutes question answered 429 is asked again after its Retry-After, at most this many times in a row. */
+export declare const LIVE_AVATAR_MINUTES_BUSY_RETRIES = 2;
+/** ★ BOFF-9446: the check after a plan purchase asks at most this many times… */
+export declare const LIVE_AVATAR_PURCHASE_POLLS = 5;
+/**
+ * …this far apart (0, 6, 12, 18 and 24 s from its first question, which itself comes at least this long after the last availability
+ * question of any kind), and stops as soon as the credits available rise.
+ */
+export declare const LIVE_AVATAR_PURCHASE_POLL_MS = 6000;
 export type LiveAvatarPhase = 
 /** Nothing running. */
 'off'
@@ -29,7 +43,10 @@ export type LiveAvatarPhase =
  | 'ready'
 /** Ending the session. */
  | 'ending';
-export type LiveAvatarNotice = 'interrupted' | 'voice-only' | 'time-limit';
+/** `minutes-ended` (★ BOFF-9446): the time limit of a session whose length was its minutes (D' < D): its minutes ran out. */
+export type LiveAvatarNotice = 'interrupted' | 'voice-only' | 'time-limit' | 'minutes-ended';
+/** ★ BOFF-9446: the bounded check after a plan purchase (`checkMinutesPurchase`): `checking` while it runs. */
+export type LiveAvatarPurchaseCheck = 'idle' | 'checking';
 /** A Turn off this soon after the tab's start click is the second click of a double click, not a choice (BOFF-9341, critic #2). */
 export declare const LIVE_AVATAR_TAB_OFF_GUARD_MS = 1000;
 export interface LiveAvatarSnapshot {
@@ -76,6 +93,25 @@ export interface LiveAvatarSnapshot {
     readonly audioBlocked: boolean;
     /** The avatar's video has arrived. */
     readonly videoReady: boolean;
+    /**
+     * ★ BOFF-9446: the minutes block of the latest availability answer (the server sends one in `enforce` only), or null: no answer with
+     * one yet (today's answers never have one), an answer with none since, or cleared by a workspace switch or a "not offered" answer.
+     * A quiet question (`refreshMinutes`) replaces it; it never changes the phase, and changes the problem only to settle a minutes
+     * problem that has no time of its own (see `refreshMinutes`).
+     */
+    readonly minutes: AvatarMinutes | null;
+    /** ★ BOFF-9446: with the problem `minutes-exhausted`, the reason the server or the minutes answer gave; null otherwise. Goes with it. */
+    readonly minutesReason: AvatarMinutesReason | null;
+    /** ★ BOFF-9446: the running session's minutes, from its start answer (enforce only); null otherwise. Set at `ready`. */
+    readonly sessionMinutes: AvatarSessionMinutes | null;
+    /**
+     * ★ BOFF-9446: wall-clock ms at which the server ends the running session (create sent + D' - 5 s). Measured on the local scheduler
+     * from the moment the create was sent, and placed on the local clock once, at `ready`: never the server's wall clock. Null unless the
+     * start answered D'.
+     */
+    readonly sessionEndsAt: number | null;
+    /** ★ BOFF-9446: the bounded check after a plan purchase (`checkMinutesPurchase`). */
+    readonly purchase: LiveAvatarPurchaseCheck;
 }
 /** The person's stored choices (P4), read and written through this narrow port so tests need no storage. */
 export interface LiveAvatarPreferences {
@@ -125,6 +161,10 @@ export interface LiveAvatarControllerDeps {
     readonly newIdempotencyKey: () => string;
     readonly subscribeWorkspaceChange?: (listener: () => void) => () => void;
     readonly subscribePageHide?: (listener: () => void) => () => void;
+    /** ★ BOFF-9446: the page is shown now; no quiet minutes question is asked while it is hidden. Absent: always shown. */
+    readonly isPageVisible?: () => boolean;
+    /** ★ BOFF-9446: called when the page is shown again (after it was hidden): the minutes are asked again then, quietly. */
+    readonly subscribePageVisible?: (listener: () => void) => () => void;
     /**
      * The page is shown again (its document visible again, or shown from the back/forward cache): the listener is `recheckRetry`. The
      * scheduler's monotonic clock does not count a system sleep, so after one a refusal's timer fires late; the wall clock (`now`) does.
@@ -180,6 +220,28 @@ export interface LiveAvatarController {
     setTabOpen(open: boolean): void;
     /** The person declined the disclosure. */
     cancelChoice(): void;
+    /**
+     * ★ BOFF-9446: ask availability again, QUIETLY, for its minutes only (the host's own reasons, such as the app coming back from its
+     * billing pages; the controller asks by itself after an end, when the tab opens and when the page is shown again). The phase and the
+     * chooser never change, no problem is raised, and a failure, a 429 included, keeps the last answer. The newer minutes settle a minutes
+     * problem that has no time of its own (none left, in use, not set up: Turn on cannot start), as `confirm` would find them: it says
+     * what they rule out, or goes when they leave room for a start (AVAILABLE, UNAVAILABLE, no block). A refusal with a time (`retryAt`)
+     * waits for it, and the zero-session limit stays (no minutes answer reports it). It asks only once the server has sent minutes (with
+     * today's answers it asks nothing), only while the avatar is offered and off or choosing, never while the page is hidden, never before
+     * the Retry-After of the last 429 to an availability question, and at most once per `LIVE_AVATAR_MINUTES_REFRESH_MS` (one asked sooner
+     * waits for it).
+     */
+    refreshMinutes(): void;
+    /**
+     * ★ BOFF-9446: the person came back from a plan checkout. `purchase` is `checking` while up to `LIVE_AVATAR_PURCHASE_POLLS`
+     * quiet questions are asked, `LIVE_AVATAR_PURCHASE_POLL_MS` apart, the first no sooner than that after the last availability question
+     * of any kind; it stops as soon as the credits available rise above what they were when it began. Its answers settle the credits
+     * problem as a quiet question's do (`refreshMinutes`). Called while a check runs, the check starts again with all its questions, at
+     * the same pace. A tick is skipped, and counted, while the page is hidden, while another availability question is out, or before the
+     * Retry-After of the last 429 to one. Only once the server has sent minutes (`minutes` not null): a call before then is dropped, not
+     * remembered, so the host calls it once the snapshot has minutes.
+     */
+    checkMinutesPurchase(): void;
     selectAvatar(avatarId: string): void;
     /**
      * Avatar OFF: the toggle, the compact view's stop, the tab's Turn off, the end of the voice conversation (P2). Idempotent. In the tab,