@cortexkit/antigravity-auth-core 3.0.7 → 3.0.9

package/dist/common-auth-embedded/claustrum/insula.d.ts

@@ -1,4 +1,5 @@
 import type { ClaustrumClientOptions } from '@cortexkit/claustrum-client';
+import { type WatchMode } from './watch.js';
 /** Insula's window fields are open: plugins choose which limits they understand. */
 export interface InsulaUsageWindow {
     usedPercent: number;
@@ -33,6 +34,27 @@ export interface InsulaQuotaContext {
     fetchedAt: number;
     source?: string;
 }
+export type InsulaQuotaMiss = 'cold' | 'stale' | 'absent' | 'upstream-failed' | 'credential' | 'unreachable';
+export interface InsulaQuotaReading {
+    entry: InsulaUsageEntry;
+    context: InsulaQuotaContext;
+}
+/** A miss may retain a dated reading; it is not a current quota observation. */
+export type InsulaQuotaLookup = {
+    reading: InsulaQuotaReading;
+    miss?: never;
+} | {
+    miss: InsulaQuotaMiss;
+    reading?: InsulaQuotaReading;
+};
+/** The normalized equivalent of a source lookup, for a plugin's quota type. */
+export type InsulaQuotaResult<Q> = {
+    reading: Q;
+    miss?: never;
+} | {
+    miss: InsulaQuotaMiss;
+    reading?: Q;
+};
 export interface InsulaQuotaOptions<Q> {
     provider: 'codex' | 'claude' | 'antigravity';
     /**
@@ -43,25 +65,74 @@ export interface InsulaQuotaOptions<Q> {
      */
     normalize: (entry: InsulaUsageEntry, context: InsulaQuotaContext) => Q | undefined;
 }
+/**
+ * A held-open `usage.watch` stream. `closed` resolves when insula ends the
+ * stream (STREAM_END at shutdown, or a reply that ends it) or after `stop()`,
+ * and rejects with insula's refusal (an error with a `code`, such as
+ * `unknown_method` from an insula that predates the method, or
+ * `usage_watch_limit` when 64 watches are already open) or with the
+ * transport failure.
+ */
+export interface InsulaUsageWatch {
+    stop(): void;
+    readonly closed: Promise<void>;
+}
 /** Optional transport for custom scoped clients; getUsage must not retry refusals. */
 export interface InsulaUsageTransport {
     connectionFile: string;
     getUsage(): Promise<unknown>;
+    /**
+     * Open a `usage.watch` stream, passing each notice's raw JSON body to
+     * `onNotice`. Optional: a transport without it is polled as before.
+     */
+    watchUsage?(onNotice: (body: Uint8Array) => void): InsulaUsageWatch;
 }
 /** Constructing this transport opens no connection; getUsage opens one per call. */
 export declare function insulaUsageTransport(options: ClaustrumClientOptions & {
     connectionFile: string;
 }): InsulaUsageTransport;
+export interface InsulaWatchOptions {
+    /**
+     * The provider this watcher reads. A notice that names only other
+     * providers then needs no read; unset means every notice does.
+     */
+    provider?: string;
+    /**
+     * setTimeout and clearTimeout for the waits before re-subscribing or retrying
+     * a watch. Defaults to the global timers; tests inject virtual ones.
+     */
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+}
 export declare class InsulaQuotaSource {
     #private;
     private readonly transport;
     private readonly key;
     constructor(transport: InsulaUsageTransport, key: string);
+    /**
+     * The background poll: at most one usage.get per minute per daemon and
+     * enrollment token. While a watch is open it reads nothing, because insula's
+     * notices announce every new reading. If insula stops announcing an account,
+     * that account's last entry grows older than the freshness limit `current()`
+     * applies, `current()` returns nothing for it, and the plugin falls back to
+     * its own provider poll for that account.
+     */
     refresh(now: number): Promise<void>;
+    /** How this source currently learns about usage changes, for logs. */
+    watchMode(): WatchMode;
+    /**
+     * Hold a `usage.watch` open while any watcher wants it, and re-read
+     * usage.get when a notice says something changed. Watchers of one source
+     * share one watch, since insula admits only 64 per process. Returns the
+     * release; the last release closes the watch.
+     */
+    watch(options?: InsulaWatchOptions): () => void;
     current(provider: string, accountId: string, now: number): {
         entry: InsulaUsageEntry;
         context: InsulaQuotaContext;
     } | undefined;
+    /** Cache-only background lookup; current() retains its original miss behavior. */
+    lookup(provider: string, accountId: string, now: number): InsulaQuotaLookup;
 }
 export declare function acquireInsulaQuotaSource(transport: InsulaUsageTransport, tokenPath: string): {
     source: InsulaQuotaSource;

package/dist/common-auth-embedded/claustrum/insula.js

@@ -5,6 +5,8 @@ import { storeIdentity } from '@cortexkit/claustrum-client';
 // import makes bundlers emit a separate chunk that a running host loses when
 // its dist folder is rebuilt underneath it.
 import { SubcClient } from '@cortexkit/subc-client';
+import { classifyVaultFailure } from './availability.js';
+import { ChangeNoticeReader, CoalescedRead, RESUBSCRIBE_BACKOFF_MS, WATCH_RETRY_MS, } from './watch.js';
 /** Constructing this transport opens no connection; getUsage opens one per call. */
 export function insulaUsageTransport(options) {
     const identity = options.identity ??
@@ -49,10 +51,86 @@ export function insulaUsageTransport(options) {
                 client?.close();
             }
         },
+        watchUsage(onNotice) {
+            // The watch holds its own connection for as long as it is open: each
+            // usage.get above opens and closes a short-lived one, and the scoped
+            // credential connection is never shared with insula. The method name
+            // alone makes the request a watch; subc-client does not yet set the
+            // SUBSCRIPTION flag, and insula does not require it.
+            let client;
+            let subscription;
+            let stopped = false;
+            const closed = (async () => {
+                let deadline;
+                const timeout = new Promise((_resolve, reject) => {
+                    deadline = setTimeout(
+                    // Coded as a timeout, so InsulaQuotaSource treats a watch that could
+                    // not open in time as an unreachable insula and tries again later,
+                    // not as a refusal.
+                    () => reject(Object.assign(new Error('insula watch timeout'), {
+                        code: 'timeout',
+                    })), 3_000);
+                    deadline.unref?.();
+                });
+                const open = (async () => {
+                    const handshakeTimeoutMs = Math.min(options.handshakeTimeoutMs ?? 3_000, 3_000);
+                    const connected = options.connector
+                        ? await options.connector({
+                            connectionFile: options.connectionFile,
+                            handshakeTimeoutMs,
+                        })
+                        : await SubcClient.connect({
+                            connectionFile: options.connectionFile,
+                            handshakeTimeoutMs,
+                        });
+                    client = connected;
+                    // A connection that arrives after stop() or after the open deadline
+                    // must not keep a route or socket alive.
+                    if (stopped) {
+                        connected.close();
+                        return;
+                    }
+                    const route = await connected.routeOpen({ kind: 'management_surface', module_id: 'insula' }, identity);
+                    if (stopped) {
+                        connected.close();
+                        return;
+                    }
+                    subscription = connected.subscribe(route, { method: 'usage.watch' }, onNotice);
+                })();
+                try {
+                    await Promise.race([open, timeout]);
+                }
+                catch (error) {
+                    stopped = true;
+                    throw error;
+                }
+                finally {
+                    clearTimeout(deadline);
+                }
+                if (subscription)
+                    await subscription.closed;
+            })().finally(() => {
+                stopped = true;
+                client?.close();
+            });
+            return {
+                stop() {
+                    if (stopped)
+                        return;
+                    stopped = true;
+                    subscription?.unsubscribe();
+                    client?.close();
+                },
+                closed,
+            };
+        },
     };
 }
 const MINUTE = 60_000;
 const MAX_AGE = 4 * MINUTE;
+// consumer-contract.md:331 refetches a slot after 60 s. Two such intervals
+// bound our willingness to wait, not a claim that insula completed its sweep.
+const COLD_WAIT = 2 * MINUTE;
 const sources = new Map();
 // Keep only the minute budget after the last owner closes, so project churn
 // cannot reset the bound. Expired budgets are pruned on the next tick.
@@ -60,18 +138,107 @@ const attempts = new Map();
 function record(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function decodeUsageNotice(body) {
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(body));
+    }
+    catch {
+        return undefined;
+    }
+    if (!record(value) ||
+        typeof value.kind !== 'string' ||
+        typeof value.epoch !== 'string' ||
+        value.epoch.length === 0 ||
+        typeof value.seq !== 'number' ||
+        !Number.isSafeInteger(value.seq) ||
+        value.seq < 1 ||
+        (value.provider !== undefined && typeof value.provider !== 'string'))
+        return undefined;
+    return {
+        kind: value.kind,
+        epoch: value.epoch,
+        seq: value.seq,
+        ...(typeof value.provider === 'string' && { provider: value.provider }),
+    };
+}
+function refusalCode(error) {
+    return error instanceof Error &&
+        'code' in error &&
+        typeof error.code === 'string'
+        ? error.code
+        : undefined;
+}
 export class InsulaQuotaSource {
     transport;
     key;
     #entries = [];
-    #pending;
+    #available = false;
+    #completeProviders = new Set();
+    #coldSince = new Map();
+    /** Every usage.get, polled or watch-driven, shares this one slot. */
+    #reads = new CoalescedRead(async () => {
+        try {
+            const reply = await this.transport.getUsage();
+            if (!record(reply) ||
+                !Array.isArray(reply.result) ||
+                reply.error !== undefined)
+                throw new Error('unavailable insula usage');
+            // Each response is a snapshot, not a delta. Only completeProviders
+            // asserts completeness; neither pending nor the entry count does.
+            this.#entries = reply.result.filter((entry) => record(entry) && typeof entry.provider === 'string');
+            this.#available =
+                this.#entries.length === reply.result.length &&
+                    (reply.completeProviders === undefined ||
+                        (Array.isArray(reply.completeProviders) &&
+                            reply.completeProviders.every((value) => typeof value === 'string')));
+            this.#completeProviders = new Set(this.#available && Array.isArray(reply.completeProviders)
+                ? reply.completeProviders
+                : []);
+            for (const provider of this.#completeProviders)
+                this.#coldSince.delete(provider);
+        }
+        catch {
+            // Refusal is absence, even if the previous reading was still young.
+            this.#entries = [];
+            this.#available = false;
+            this.#completeProviders.clear();
+        }
+    }, () => { });
+    #reader = new ChangeNoticeReader();
+    #mode = 'polling';
+    #watchers = 0;
+    /**
+     * How many registered watchers read every provider. Watchers limited to one
+     * provider are counted per provider in `#providers` instead.
+     */
+    #everyProvider = 0;
+    #providers = new Map();
+    #watch;
+    #timer;
+    #timers = {};
+    /**
+     * How many accepted watches in a row have closed; each one doubles the wait
+     * before the next re-subscribe. Reset once a watch brings a second notice.
+     */
+    #closes = 0;
     constructor(transport, key) {
         this.transport = transport;
         this.key = key;
     }
+    /**
+     * The background poll: at most one usage.get per minute per daemon and
+     * enrollment token. While a watch is open it reads nothing, because insula's
+     * notices announce every new reading. If insula stops announcing an account,
+     * that account's last entry grows older than the freshness limit `current()`
+     * applies, `current()` returns nothing for it, and the plugin falls back to
+     * its own provider poll for that account.
+     */
     refresh(now) {
-        if (this.#pending)
-            return this.#pending;
+        if (this.#reads.running)
+            return this.#reads.running;
+        if (this.#mode === 'watching')
+            return Promise.resolve();
         for (const [key, time] of attempts) {
             if (now - time >= MINUTE)
                 attempts.delete(key);
@@ -81,25 +248,141 @@ export class InsulaQuotaSource {
             return Promise.resolve();
         // Reserve the minute before I/O, so concurrent projects cannot each poll.
         attempts.set(this.key, now);
-        this.#pending = (async () => {
-            try {
-                const reply = await this.transport.getUsage();
-                if (!record(reply) ||
-                    !Array.isArray(reply.result) ||
-                    reply.error !== undefined)
-                    throw new Error('unavailable insula usage');
-                // Each response is a snapshot, not a delta. Missing accounts fall back;
-                // neither pending nor the entry count asserts provider completeness.
-                this.#entries = reply.result.filter((entry) => record(entry) && typeof entry.provider === 'string');
-            }
-            catch {
-                // Refusal is absence, even if the previous reading was still young.
-                this.#entries = [];
+        return this.#reads.request();
+    }
+    /** How this source currently learns about usage changes, for logs. */
+    watchMode() {
+        return this.#mode;
+    }
+    /**
+     * Hold a `usage.watch` open while any watcher wants it, and re-read
+     * usage.get when a notice says something changed. Watchers of one source
+     * share one watch, since insula admits only 64 per process. Returns the
+     * release; the last release closes the watch.
+     */
+    watch(options = {}) {
+        this.#watchers++;
+        const provider = options.provider;
+        if (provider === undefined)
+            this.#everyProvider++;
+        else
+            this.#providers.set(provider, (this.#providers.get(provider) ?? 0) + 1);
+        if (this.#watchers === 1) {
+            this.#timers = options;
+            this.#open();
+        }
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            if (provider === undefined)
+                this.#everyProvider--;
+            else {
+                const left = (this.#providers.get(provider) ?? 1) - 1;
+                if (left > 0)
+                    this.#providers.set(provider, left);
+                else
+                    this.#providers.delete(provider);
             }
-        })().finally(() => {
-            this.#pending = undefined;
-        });
-        return this.#pending;
+            if (--this.#watchers === 0)
+                this.#stopWatch();
+        };
+    }
+    #stopWatch() {
+        if (this.#timer)
+            (this.#timers.clearTimeoutImpl ?? clearTimeout)(this.#timer);
+        this.#timer = undefined;
+        const watch = this.#watch;
+        this.#watch = undefined;
+        watch?.handle?.stop();
+        this.#mode = 'polling';
+    }
+    #later(delay) {
+        this.#timer = (this.#timers.setTimeoutImpl ?? setTimeout)(() => {
+            this.#timer = undefined;
+            if (this.#watchers > 0 && !this.#watch)
+                this.#open();
+        }, delay);
+        this.#timer.unref?.();
+    }
+    #open() {
+        const watchUsage = this.transport.watchUsage;
+        if (!watchUsage) {
+            // A custom transport that cannot watch: poll exactly as before.
+            this.#mode = 'fallback';
+            return;
+        }
+        this.#mode = 'polling';
+        this.#reader.restart();
+        const watch = { notices: 0 };
+        this.#watch = watch;
+        let handle;
+        try {
+            handle = watchUsage.call(this.transport, (body) => this.#notice(watch, body));
+        }
+        catch (error) {
+            this.#closed(watch, error);
+            return;
+        }
+        watch.handle = handle;
+        handle.closed.then(() => this.#closed(watch, undefined), (error) => this.#closed(watch, error));
+    }
+    #notice(watch, body) {
+        // Frames already in transport can arrive after a local stop.
+        if (this.#watch !== watch)
+            return;
+        watch.notices++;
+        if (watch.notices === 1)
+            this.#mode = 'watching';
+        // A second notice means the watch stayed up past its acceptance.
+        if (watch.notices === 2)
+            this.#closes = 0;
+        const notice = decodeUsageNotice(body);
+        // An unreadable notice may hide any change: treat it as a break, and
+        // make the next notice read as one too.
+        if (!notice)
+            this.#reader.restart();
+        const continuous = notice ? this.#reader.continuous(notice) : false;
+        // The first notice of every watch names no provider, so it always reads:
+        // nothing was watched before it. After a gap or a new epoch notices were
+        // lost, so read even when this notice names another provider.
+        if (!continuous ||
+            notice?.provider === undefined ||
+            this.#everyProvider > 0 ||
+            this.#providers.has(notice.provider))
+            void this.#reads.request();
+    }
+    #closed(watch, error) {
+        if (this.#watch !== watch)
+            return;
+        this.#watch = undefined;
+        const code = refusalCode(error);
+        if (code === 'unknown_method' || code === 'usage_watch_limit') {
+            // An insula that predates usage.watch, or one already holding 64
+            // watches: poll exactly as before until every watcher has released.
+            this.#mode = 'fallback';
+            return;
+        }
+        if (watch.notices > 0) {
+            // An accepted watch that closed (insula shut down, or the connection
+            // dropped) gets one new watch, whose first notice reads usage.get.
+            const delay = Math.min(RESUBSCRIBE_BACKOFF_MS * 2 ** Math.min(this.#closes, 16), WATCH_RETRY_MS);
+            this.#closes++;
+            this.#mode = 'polling';
+            this.#later(delay);
+            return;
+        }
+        // Closed before any notice, so never accepted: read once to learn
+        // whether insula answers at all, then poll as before. A refusal insula
+        // answered stands until every watcher has released. A close it did not
+        // explain (a
+        // dropped connection, a timeout, a stream ended at once while insula
+        // shuts down) earns one new watch much later.
+        this.#mode = 'fallback';
+        void this.#reads.request();
+        if (error === undefined || classifyVaultFailure(error) === 'unreachable')
+            this.#later(WATCH_RETRY_MS);
     }
     current(provider, accountId, now) {
         for (const entry of this.#entries) {
@@ -126,6 +409,50 @@ export class InsulaQuotaSource {
         }
         return undefined;
     }
+    /** Cache-only background lookup; current() retains its original miss behavior. */
+    lookup(provider, accountId, now) {
+        if (!this.#available)
+            return { miss: 'unreachable' };
+        const entry = this.#entries.find((value) => value.provider === provider &&
+            typeof value.account === 'string' &&
+            value.account.trim() === accountId);
+        // An unlabelled error describes the provider's credential path, not an
+        // unrelated labelled account. Never borrow another account's verdict.
+        const errorClass = (entry ??
+            this.#entries.find((value) => value.provider === provider &&
+                value.account === undefined &&
+                value.errorClass !== undefined))?.errorClass;
+        if (errorClass === 'upstream_failed')
+            return { miss: 'upstream-failed' };
+        if (errorClass === 'credential_absent' ||
+            errorClass === 'credential_unusable' ||
+            errorClass === 'credential_rejected')
+            return { miss: 'credential' };
+        if (errorClass !== undefined)
+            return { miss: 'unreachable' };
+        if (entry) {
+            const fetchedAt = typeof entry.fetchedAt === 'string'
+                ? Date.parse(entry.fetchedAt)
+                : Number.NaN;
+            if (!record(entry.usage) || !Number.isFinite(fetchedAt))
+                return { miss: 'unreachable' };
+            const reading = {
+                entry,
+                context: {
+                    fetchedAt,
+                    ...(typeof entry.source === 'string' && { source: entry.source }),
+                },
+            };
+            return now >= fetchedAt + MAX_AGE || entry.stale !== undefined
+                ? { miss: 'stale', reading }
+                : { reading };
+        }
+        if (this.#completeProviders.has(provider))
+            return { miss: 'absent' };
+        const since = this.#coldSince.get(provider) ?? now;
+        this.#coldSince.set(provider, since);
+        return { miss: now - since >= COLD_WAIT ? 'unreachable' : 'cold' };
+    }
 }
 export function acquireInsulaQuotaSource(transport, tokenPath) {
     const key = JSON.stringify([

package/dist/common-auth-embedded/claustrum/watch.d.ts

@@ -0,0 +1,141 @@
+import type { ClaustrumLogger } from './errors.js';
+/**
+ * How a host currently learns about changes, for logs and status displays.
+ * `watching`: a watch was accepted and is open, so polling is reduced to a
+ * slow safety read. `polling`: no watch is open yet (not started, opening, or
+ * re-subscribing after a close), so the host polls at its usual interval.
+ * `fallback`: the watch is unavailable (an older module or client, a refusal,
+ * the watch limit, or repeated failures), so the host polls at its usual
+ * interval and may try a watch again later. Never carries secrets.
+ */
+export type WatchMode = 'watching' | 'polling' | 'fallback';
+/**
+ * While a vault watch is healthy, the roster is still read this often: the
+ * watch carries no history, so a lost notice or a silently dead stream is
+ * caught within this period.
+ */
+export declare const SAFETY_POLL_MS: number;
+/**
+ * After a watch fails without being accepted, the host polls and tries one
+ * new watch this much later, so a refusing or draining module is never asked
+ * in a tight loop.
+ */
+export declare const WATCH_RETRY_MS: number;
+/**
+ * First wait before re-subscribing a watch that closed after it had been
+ * accepted. It doubles for each further close in a row, up to WATCH_RETRY_MS.
+ */
+export declare const RESUBSCRIBE_BACKOFF_MS = 1000;
+/**
+ * The fields every change notice carries, from the vault's watchScoped and
+ * insula's usage.watch alike.
+ */
+export interface ChangeNotice {
+    readonly kind: string;
+    readonly epoch: string;
+    readonly seq: number;
+}
+/**
+ * Tells whether a notice follows the previous one with nothing lost between
+ * them. `seq` restarts at 1 for every watch and `epoch` names the sending
+ * module's process lifetime. A sequence gap (notices are sheddable), a
+ * different epoch (the module restarted) or a notice of an unknown kind all
+ * mean changes may have been missed, so the caller must re-read everything.
+ */
+export declare class ChangeNoticeReader {
+    #private;
+    /**
+     * Begin a new watch, whose first notice is seq 1 again. The epoch is kept,
+     * so a module restart between two watches still reads as a break.
+     */
+    restart(): void;
+    continuous(notice: ChangeNotice): boolean;
+}
+/**
+ * Runs `read` with at most one call in flight and at most one more queued
+ * behind it, however many requests arrive meanwhile. A request made while a
+ * read is running may have arrived after that read took its snapshot, so it
+ * earns exactly one more read; any further requests share that one.
+ */
+export declare class CoalescedRead {
+    #private;
+    constructor(read: () => Promise<void>, onError: (error: unknown) => void);
+    /** The read in flight (including its queued follow-up), if any. */
+    get running(): Promise<void> | undefined;
+    request(): Promise<void>;
+}
+/** A vault watch notice: `view` is the same digest `list_scoped` returns. */
+export interface ScopedWatchNoticeShape extends ChangeNotice {
+    readonly view: string;
+}
+/**
+ * How a vault watch ended, as claustrum-client 0.12.0 reports it. `refused`
+ * and `not_accepting` both mean the watch closed before its first notice; the
+ * client then made one `list_scoped` read to learn why, and `refused` carries
+ * that read's refusal.
+ */
+export type ScopedWatchEnd = {
+    readonly kind: 'refused';
+    readonly error: unknown;
+} | {
+    readonly kind: 'transport_lost';
+    readonly error: unknown;
+} | {
+    readonly kind: 'ended' | 'not_accepting' | 'unsupported' | 'stopped';
+};
+export interface ScopedWatchHandle {
+    stop(): void;
+    readonly closed: Promise<ScopedWatchEnd>;
+}
+/**
+ * The part of a vault client that can watch. claustrum-client added
+ * `watchScoped` in 0.12.0; the peer range still admits 0.6.2, so it is
+ * optional and detected at run time.
+ */
+export interface ScopedWatchSource {
+    watchScoped?(onNotice: (notice: ScopedWatchNoticeShape) => void, options?: {
+        enrollmentToken?: string;
+    }): ScopedWatchHandle;
+}
+export interface ScopedRosterWatchOptions {
+    client: ScopedWatchSource;
+    /** The enrollment token, read again for every watch so a new one is used. */
+    enrollmentToken: () => Promise<string>;
+    /** The view of the roster this host last discovered; undefined for none. */
+    view: () => string | undefined;
+    /**
+     * The host's existing discovery: `list_scoped`, the roster commit and
+     * everything that follows it. The watch never reads the vault list itself.
+     * `view` is the view the newest notice carried.
+     */
+    discover: (view: string) => Promise<unknown>;
+    /**
+     * The vault refused the watch, and the confirming `list_scoped` read it
+     * with this error (a revoked enrollment ends both with `not_found`). Handle
+     * it as discovery handles the same refusal from `list_scoped`.
+     */
+    onRefused: (error: unknown) => void;
+    onTransportLost?: () => void;
+    onReachable?: () => void;
+    onError?: (error: unknown) => void;
+    onMode?: (mode: WatchMode) => void;
+    logger?: ClaustrumLogger;
+    now?: () => number;
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+}
+/**
+ * Keeps one vault `watchScoped` open for a host and runs the host's discovery
+ * when a notice shows the visible account list changed. Discovery runs only
+ * when the notice's view differs from the last discovered roster's view, when
+ * a notice shows a gap or a new epoch, or on the first notice of a watch that
+ * was re-subscribed after a close (the time between two watches was not
+ * observed). It never opens a second watch while one is open.
+ */
+export declare class ScopedRosterWatch {
+    #private;
+    constructor(options: ScopedRosterWatchOptions);
+    get mode(): WatchMode;
+    start(): void;
+    stop(): void;
+}