@cortexkit/anthropic-auth-core 2.0.3 → 2.1.1

package/dist/insula-quota.d.ts

@@ -0,0 +1,25 @@
+import type { InsulaQuotaContext, InsulaUsageEntry } from "./internal-types/claustrum/index.js";
+import { type AccountQuotaWindow, type AccountScopedQuotaWindow, type OAuthQuotaSnapshot } from './accounts.ts';
+/** An insula reading in the shape our usage poll produces, before the account identity is attached. */
+export type InsulaClaudeQuota = OAuthQuotaSnapshot & {
+    five_hour: AccountQuotaWindow;
+    seven_day: AccountQuotaWindow;
+    scoped: AccountScopedQuotaWindow[];
+    checkedAt: number;
+};
+/**
+ * Convert insula's Claude entry into our usage-poll snapshot. Every window's
+ * checkedAt is when insula fetched the reading, never when we read its cache,
+ * so a newer header or poll reading still wins. Both standard windows must be
+ * present; otherwise this returns undefined and our own poll stays in charge.
+ * The tertiary slot (legacy seven_day_opus/sonnet) is not a window we model.
+ */
+export declare function normalizeInsulaClaudeQuota(entry: InsulaUsageEntry, context: InsulaQuotaContext): InsulaClaudeQuota | undefined;
+/**
+ * Insula fetches on its own schedule, so the account's stored quota can hold
+ * a window read after insula's fetch (a response header, or our own poll).
+ * Stored quota is replaced as one snapshot, newest wins, so publishing the
+ * older insula reading as is would be refused and lose its other windows.
+ * Keep the newer reading of each window instead.
+ */
+export declare function mergeInsulaQuota(reading: InsulaClaudeQuota, stored: OAuthQuotaSnapshot | undefined): OAuthQuotaSnapshot;

package/dist/internal-types/claustrum/availability.d.ts

@@ -0,0 +1,89 @@
+import { ClaustrumConsumerError } from './errors.js';
+export type VaultFailureClass = 'unreachable' | 'answered';
+/**
+ * Codes from claustrum-client's decoder and its subc transport. A retry action
+ * alone is not evidence of an outage: even transient vault refusals must win
+ * over a previously served credential. New codes fail closed until reviewed.
+ */
+export declare const VAULT_FAILURE_CLASSES: Readonly<{
+    ECONNREFUSED: "unreachable";
+    ENOENT: "unreachable";
+    ECONNRESET: "unreachable";
+    EPIPE: "unreachable";
+    ETIMEDOUT: "unreachable";
+    transport_error: "unreachable";
+    unavailable: "unreachable";
+    timeout: "unreachable";
+    route_closed: "unreachable";
+    daemon_draining: "unreachable";
+    connection_closed: "unreachable";
+    connection_dropped: "unreachable";
+    request_deadline: "unreachable";
+    deadline_exceeded_no_drop_observed: "unreachable";
+    module_reloading: "unreachable";
+    module_warming: "unreachable";
+    target_unavailable: "unreachable";
+    module_timeout: "unreachable";
+    invalid_response: "answered";
+    invalid_record_version: "answered";
+    invalid_expiry: "answered";
+    invalid_status: "answered";
+    invalid_params: "answered";
+    ttl_unsatisfiable: "answered";
+    not_found: "answered";
+    enrollment_revoked: "answered";
+    enrollment_invalid: "answered";
+    grant_denied: "answered";
+    credential_unavailable: "answered";
+    needs_reauth: "answered";
+    declined: "answered";
+    disabled: "answered";
+    identity_changed: "answered";
+    closed: "answered";
+    client_closed: "answered";
+    pending_exists: "answered";
+    pending_queue_full: "answered";
+    already_consumed: "answered";
+    superseded: "answered";
+    stale_generation: "answered";
+    missing_identity: "answered";
+    invalid_control_body: "answered";
+    unknown_module: "answered";
+    module_removed: "answered";
+    capability_denied: "answered";
+    unknown_channel: "unreachable";
+    stale_route_epoch: "unreachable";
+    capability_forbidden: "answered";
+    capability_unprovided: "answered";
+    capability_ambiguous: "answered";
+    invalid_capability_identifier: "answered";
+    binary_body_required: "answered";
+    binary_call_requires_call_binary: "answered";
+    corr_exhausted: "answered";
+    late_route_cleanup_failed: "answered";
+    reverse_request_capability_not_declared: "answered";
+    stale_route_handle: "answered";
+    reverse_request_unhandled: "answered";
+    handler_error: "answered";
+    health_error: "answered";
+    duplicate_module_id: "answered";
+    route_rejected: "answered";
+    lock_busy: "answered";
+    owner_invalid: "answered";
+    renewal_failed: "answered";
+    unsupported_platform: "answered";
+    EACCES: "answered";
+    EPERM: "answered";
+    ERR_PRIVATE_FILES_SECURITY: "answered";
+}>;
+/**
+ * An injected adapter may throw this ONLY when its connection/transport is
+ * unreachable, including a failed connect before getScoped. Do not wrap an
+ * adapter shutdown, cancellation, validation error or vault refusal in it.
+ * Its fixed message cannot echo enrollment or credential material, and its
+ * kind stays `unavailable` for callers handling ClaustrumConsumerError.
+ */
+export declare class ClaustrumUnreachableError extends ClaustrumConsumerError {
+    constructor();
+}
+export declare function classifyVaultFailure(error: unknown): VaultFailureClass;

package/dist/internal-types/claustrum/consumer.d.ts

@@ -1,10 +1,11 @@
 import type { ClaustrumReporterSource } from '@cortexkit/claustrum-client';
 import type { QuotaObservation } from '../quota/index.js';
 import type { RoutingRow } from '../routing/index.js';
-import { type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, type IdentityParser } from './custody.js';
+import { type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, type IdentityParser, type KeptReceiptState, type VaultGrantReach } from './custody.js';
 import { type ClaustrumLogger } from './errors.js';
 import { type InsulaQuotaOptions } from './insula.js';
 import { type AccountMapper, type QuotaReceipt, type VaultRosterFile } from './roster.js';
+import { type WatchMode } from './watch.js';
 export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
     /**
      * The roster file: one row per vault account (route id, credential id,
@@ -41,6 +42,12 @@ export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
      */
     onRoster?: (roster: VaultRosterFile) => void;
     onError?: (error: unknown) => void;
+    /**
+     * How often `start()` ticks. A tick lists the vault when no vault watch is
+     * open (before it is accepted, or when the vault or the client cannot
+     * watch), and otherwise only every five minutes, as a safety net. A tick
+     * polls insula (at most once a minute) only while its watch is not open.
+     */
     pollIntervalMs?: number;
     setTimeoutImpl?: typeof setTimeout;
     clearTimeoutImpl?: typeof clearTimeout;
@@ -49,6 +56,15 @@ export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
     /** Optional background quota source. In-band readings still use recordQuota. */
     insula?: InsulaQuotaOptions<Q>;
 }
+/**
+ * How a started consumer learns about changes, for logs and status displays.
+ * `insula` is present when the consumer was given an insula source. Never
+ * carries secrets.
+ */
+export interface ClaustrumWatchState {
+    readonly vault: WatchMode;
+    readonly insula?: WatchMode;
+}
 export interface SendOptions {
     /**
      * What kind of request this is (for example `model`, `quota`, `profile`),
@@ -71,9 +87,33 @@ export declare class ClaustrumConsumer<Q = QuotaObservation> {
     constructor(options: ClaustrumConsumerOptions<Q>);
     /** The last committed roster this instance saw, without any I/O. */
     snapshot(): VaultRosterFile | undefined;
+    /**
+     * What this consumer is granted, from its latest discovery, without any I/O.
+     * It explains an empty roster: `grants === 0` means no grant at all, while
+     * `grants > 0` means a grant that reaches no credential (`tuples` names its
+     * selector). Undefined means unknown, never zero: the vault or client is too
+     * old to send it, nothing was discovered yet, or the roster now in memory is
+     * a different view than the one this instance discovered (a peer process
+     * held the discovery lease and its newer roster was served instead).
+     */
+    grantReach(): VaultGrantReach | undefined;
+    /** How this consumer currently learns about changes, without I/O. */
+    watchState(): ClaustrumWatchState;
+    /** Whether any account is using an in-memory outage receipt, without I/O. */
+    keptReceiptState(): KeptReceiptState;
     /** Rows for `/routing`, from the last committed roster. */
     routingRows(): RoutingRow[];
     refresh(): Promise<VaultRosterFile | undefined>;
+    /**
+     * Poll in the background and open the vault and insula watches. Until the
+     * vault watch is accepted, and whenever it is unavailable, every tick lists
+     * the vault exactly as before watches existed. While it is open a tick
+     * lists only when five minutes have passed since the last discovery, since
+     * the watch keeps no history; it still checks `isCustodyActive`, so a switch
+     * to local mode closes the connection as quickly as before. Insula is
+     * polled on the tick only while its own watch is not open. A host not in
+     * vault mode makes no request.
+     */
     start(): void;
     /**
      * Fetch on a background tick, at most once per minute across projects with

package/dist/internal-types/claustrum/custody.d.ts

@@ -1,9 +1,14 @@
 import { type ClaustrumClient, type ClaustrumReporterSource, type EnrollmentTokenFile } from '@cortexkit/claustrum-client';
 import { type ClaustrumLogger } from './errors.js';
 import type { InsulaUsageTransport } from './insula.js';
+import { type ScopedWatchSource, type WatchMode } from './watch.js';
+/**
+ * `watchScoped` is present from claustrum-client 0.12.0. Hosts detect it at
+ * run time and keep polling without it.
+ */
 export type ClaustrumScopedClient = Pick<ClaustrumClient, 'listScoped' | 'getScoped' | 'reportAuthFailureScoped' | 'close'> & {
     insula?: InsulaUsageTransport;
-};
+} & ScopedWatchSource;
 /** The two credential types a plugin's family can hold; routing differs by type. */
 export type VaultCredentialType = 'oauth' | 'api_key';
 /**
@@ -44,6 +49,30 @@ export interface SkippedVaultRecord {
     readonly credentialId?: string;
     readonly reason: SkippedVaultReason;
 }
+/**
+ * One grant this consumer's enrollment holds, as the vault's list reply names
+ * it: for example `{ selectorKind: 'category', selector: 'openai-native',
+ * operation: 'read' }`. `selectorKind` is `exact` (the selector is a credential
+ * id) or `category` (a bare category name); both open strings.
+ */
+export interface VaultGrantTuple {
+    readonly selectorKind: string;
+    readonly selector: string;
+    readonly operation: string;
+}
+/**
+ * What this consumer is granted, independent of what those grants currently
+ * reach. It is what tells two empty listings apart: no rows with `grants === 0`
+ * means no grant at all (the fix is `ck auth grant`), while no rows with
+ * `grants > 0` means a grant that reaches no credential, usually logins that
+ * lack the category (`ck auth reclassify --from-registry`); `tuples` names the
+ * selector that matched nothing. Never written to the roster file.
+ */
+export interface VaultGrantReach {
+    /** How many grants the consumer holds, deposit grants excluded. */
+    readonly grants: number;
+    readonly tuples: readonly VaultGrantTuple[];
+}
 export interface VaultInventory {
     /**
      * The vault's change cursor: a digest over exactly what this consumer can see
@@ -53,6 +82,11 @@ export interface VaultInventory {
     readonly view: string;
     readonly credentials: readonly VaultCredential[];
     readonly skipped: readonly SkippedVaultRecord[];
+    /**
+     * The consumer's grants, as the vault's list reply named them. Undefined means unknown
+     * (the vault or client predates the fields), never zero grants.
+     */
+    readonly grantReach?: VaultGrantReach;
 }
 export interface ClaustrumScopedIdentity {
     readonly credentialId: string;
@@ -103,6 +137,57 @@ export interface ClaustrumScopedAttempt {
     readonly accessToken: string;
     readonly recordVersion: number;
     readonly expiresAtMs: number | null;
+    /**
+     * True when this receipt was not freshly served but is the last token kept
+     * from an earlier read, used because the vault could not be reached. A 401
+     * with such a receipt must not be retried and is not reported to the vault,
+     * which is unreachable.
+     */
+    readonly fromKeptReceipt?: true;
+}
+export interface KeptReceiptState {
+    readonly active: boolean;
+    readonly since: number | null;
+}
+export interface ClaustrumRosterWatchOptions {
+    /**
+     * Run the host's own discovery (`custody.discover()`, then its roster
+     * commit). Called with the newest notice's view when that view differs from
+     * the last discovered one, when a notice shows a sequence gap or a new
+     * epoch, and on the first notice of a watch re-opened after a close (the
+     * time between two watches was not observed). One call runs at a time;
+     * notices that arrive meanwhile earn at most one more call, which runs only
+     * if the view still differs. A rejection goes to `onError`.
+     */
+    onView: (view: string) => unknown;
+    /**
+     * The view of the roster the host last committed. Defaults to the view of
+     * the last successful `custody.discover()` (outage probes excluded). Pass it
+     * when the host can commit a roster it did not list itself (a peer process
+     * held the discovery lease) or can fail after listing.
+     */
+    view?: () => string | undefined;
+    /**
+     * Called whenever the mode changes. The watch starts in `polling`. Keep the
+     * host's own list timer at its usual pace unless the mode is `watching`.
+     */
+    onMode?: (mode: WatchMode) => void;
+    /**
+     * The vault refused the watch, and its confirming `list_scoped` read it with
+     * this error (a revoked enrollment answers `not_found`). Custody has already
+     * applied it as it applies a refused discovery (`listFailed`: every kept
+     * receipt is dropped); handle it as the host handles that refusal.
+     */
+    onRefused?: (error: unknown) => void;
+    /** A failed `onView`, or a watch that could not be opened. */
+    onError?: (error: unknown) => void;
+}
+/** A vault watch held by a custody; see `ClaustrumScopedCustody.watchRoster`. */
+export interface ClaustrumRosterWatch {
+    /** How the host currently learns about changes. */
+    readonly mode: WatchMode;
+    /** Stop the watch and its timers. Safe to call more than once. */
+    close(): void;
 }
 /** Reads the provider identity a served token executes under, when the plugin can tell. */
 export type IdentityParser = (accessToken: string) => string | undefined;
@@ -122,13 +207,15 @@ export declare function decideScopedRetryAfter401(site: string, served: Claustru
  * so it cannot expire while a long request is still using it.
  */
 export declare const SERVING_MARGIN_MS = 300000;
+/** A kept receipt needs a minute of headroom, not the vault's refresh demand. */
+export declare const KEPT_RECEIPT_MARGIN_MS = 60000;
 /**
  * Reads this consumer's vault credentials (list, fetch, 401 report), with the
- * enrollment token as authorization. Used by every host of a plugin. There is
- * deliberately no credential cache and no single-flight of credential reads:
- * each physical send is authorized by the vault, so a revoked enrollment or a
- * changed record takes effect on the next send. The enrollment token is
- * re-read per operation so an operator's reissue on disk is picked up.
+ * enrollment token as authorization. Used by every host of a plugin. Every
+ * physical send asks the vault first while reachable. Only an unreachable vault permits
+ * reuse of the last validated receipt, in memory and bounded by its expiry.
+ * The enrollment token is re-read per operation so revocation and disconnect
+ * still take effect without a process restart.
  */
 export declare class ClaustrumScopedCustody {
     #private;
@@ -148,7 +235,13 @@ export declare class ClaustrumScopedCustody {
         requireAssertion?: boolean;
         now?: () => number;
         logger?: ClaustrumLogger;
+        setTimeoutImpl?: typeof setTimeout;
+        clearTimeoutImpl?: typeof clearTimeout;
     });
+    /** A watch losing its transport is the same outage as an unreachable read. */
+    transportLost(error?: unknown): void;
+    /** Any vault answer ends transport fallback, even when it refuses access. */
+    reachable(): void;
     /**
      * List this consumer's credentials. A record that cannot be used is skipped
      * and warned about rather than failing the whole list, so one bad record
@@ -157,15 +250,23 @@ export declare class ClaustrumScopedCustody {
      */
     discover(signal?: AbortSignal): Promise<VaultInventory>;
     /**
-     * Fetch the credential for one physical send and wrap it in a fresh receipt.
-     * The vault's served identity (or, without one, the plugin's parse of the
-     * token) must equal the roster's when both are present. Without
-     * `requireAssertion`, absence on either side proves nothing and does not
-     * refuse; the receipt records what the vault asserted separately from what
-     * the roster expected. With it, a reply that does not itself name the
-     * credential id and the expected account is refused.
+     * Apply a failed account listing: any answer from the vault (a refusal such
+     * as a revoked enrollment's `not_found`) drops every kept receipt, while an
+     * unreachable vault keeps them. A vault watch that ends with the same
+     * refusal calls this too, so both paths treat it alike.
      */
-    authorize(identity: ClaustrumScopedIdentity, signal?: AbortSignal): Promise<ClaustrumScopedAttempt>;
+    listFailed(error: unknown): void;
+    /** Discard bearer material when a route is removed, declined or rebound. */
+    forget(credentialId: string): void;
+    /** Apply an already-held roster; this never fetches credentials or writes it. */
+    retain(identities: readonly (ClaustrumScopedIdentity & {
+        enabled: boolean;
+        state: string;
+    })[]): void;
+    /** A frozen, non-secret summary for a plugin's status display. */
+    keptReceiptState(): KeptReceiptState;
+    /** Ask the vault while reachable; retain one validated receipt in memory only. */
+    authorize(identity: ClaustrumScopedIdentity, signal?: AbortSignal, routeId?: string): Promise<ClaustrumScopedAttempt>;
     /**
      * Report that a send this consumer actually made was rejected. Only a 401
      * is reported (the vault refuses 429, 402 and 5xx reports), addressed by
@@ -174,5 +275,25 @@ export declare class ClaustrumScopedCustody {
      * custody did not issue is refused rather than reported.
      */
     reportFailure(attempt: ClaustrumScopedAttempt, status: number, reporterSource: ClaustrumReporterSource): Promise<void>;
+    /**
+     * Watch this consumer's visible vault accounts instead of listing them on a
+     * short timer. Opens one `watchScoped` on this custody's client and calls
+     * `onView` when the host must run its discovery (see
+     * `ClaustrumRosterWatchOptions`). A claustrum-client without `watchScoped`
+     * (before 0.12.0) or a vault that answers `unknown_method` reports
+     * `fallback` and opens nothing. A watch that closes before any notice was
+     * never accepted: the client reads once to learn why, and the watch reports
+     * `fallback` and tries one new watch after `WATCH_RETRY_MS`, never in a
+     * loop. A watch that closes after notices is re-opened after
+     * `RESUBSCRIBE_BACKOFF_MS`, doubling per close in a row. A lost transport
+     * starts this custody's outage, exactly as an unreachable call does, and
+     * the first notice of a watch ends it. Timers are unreferenced; `close()`
+     * on the returned watch or on this custody stops it.
+     *
+     * The watch keeps no history, so the host still lists on a slow timer while
+     * the mode is `watching`: every `SAFETY_POLL_MS` (five minutes). In any
+     * other mode the host keeps its usual list timer.
+     */
+    watchRoster(options: ClaustrumRosterWatchOptions): ClaustrumRosterWatch;
     close(): void;
 }

package/dist/internal-types/claustrum/errors.d.ts

@@ -11,6 +11,7 @@ export declare class ClaustrumConsumerError extends Error {
 }
 /** The structural logger every class here accepts; `/logger`'s `createLogger` satisfies it. */
 export interface ClaustrumLogger {
+    info?(message: string, data?: unknown): void;
     warn(message: string, data?: unknown): void;
     debug(message: string, data?: unknown): void;
 }

package/dist/internal-types/claustrum/index.d.ts

@@ -1,14 +1,16 @@
 import { type ClaustrumClientOptions } from '@cortexkit/claustrum-client';
 import type { ClaustrumScopedClient } from './custody.js';
 export { ClaustrumCredentialError, type ClaustrumReporterSource, type EnrollmentTokenFile, } from '@cortexkit/claustrum-client';
-export { ClaustrumConsumer, type ClaustrumConsumerOptions, type SendOptions, } from './consumer.js';
-export { type AccountIdentitySource, type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, ClaustrumScopedCustody, type ClaustrumScopedIdentity, decideScopedRetryAfter401, type IdentityParser, isScopedCredentialRotation, type ScopedRetryReason, SERVING_MARGIN_MS, type SkippedVaultReason, type SkippedVaultRecord, type VaultCredential, type VaultCredentialType, type VaultInventory, } from './custody.js';
+export { ClaustrumUnreachableError, classifyVaultFailure, VAULT_FAILURE_CLASSES, type VaultFailureClass, } from './availability.js';
+export { ClaustrumConsumer, type ClaustrumConsumerOptions, type ClaustrumWatchState, type SendOptions, } from './consumer.js';
+export { type AccountIdentitySource, type ClaustrumFamily, type ClaustrumRosterWatch, type ClaustrumRosterWatchOptions, type ClaustrumScopedAttempt, type ClaustrumScopedClient, ClaustrumScopedCustody, type ClaustrumScopedIdentity, decideScopedRetryAfter401, type IdentityParser, isScopedCredentialRotation, KEPT_RECEIPT_MARGIN_MS, type KeptReceiptState, type ScopedRetryReason, SERVING_MARGIN_MS, type SkippedVaultReason, type SkippedVaultRecord, type VaultCredential, type VaultCredentialType, type VaultGrantReach, type VaultGrantTuple, type VaultInventory, } from './custody.js';
 export { type ClaustrumEnrollmentClient, type ClaustrumEnrollmentConnection, type ClaustrumEnrollmentDisconnectResult, ClaustrumEnrollmentManager, type ClaustrumEnrollmentPaths, type ClaustrumEnrollmentResetResult, type ClaustrumEnrollmentStatus, classifyEnrollmentError, connectClaustrumEnrollmentClient, disconnectClaustrumEnrollment, type EnrollmentDisposition, enrollmentAuthority, enrollmentName, getClaustrumEnrollmentPaths, hostEnrollmentPaths, RETRYABLE_ENROLLMENT_CODES, readClaustrumEnrollmentStatus, readClaustrumEnrollmentToken, resetClaustrumEnrollmentState, TERMINAL_ENROLLMENT_CODES, } from './enrollment.js';
 export { ClaustrumConsumerError, type ClaustrumConsumerFailureKind, type ClaustrumLogger, } from './errors.js';
 export { assertHostSlotMatchesMode, assertNotCustodyPlaceholder, CUSTODY_PLACEHOLDER_PREFIX, classifyHostSlot, custodyPlaceholder, custodyPlaceholderKey, type HostSlotContent, isCustodyPlaceholder, isCustodyPlaceholderValue, } from './host-slot.js';
-export type { InsulaQuotaContext, InsulaQuotaOptions, InsulaUsageEntry, InsulaUsageTransport, InsulaUsageWindow, } from './insula.js';
+export { acquireInsulaQuotaSource, type InsulaQuotaContext, type InsulaQuotaOptions, type InsulaQuotaSource, type InsulaUsageEntry, type InsulaUsageTransport, type InsulaUsageWatch, type InsulaUsageWindow, type InsulaWatchOptions, } from './insula.js';
 export { acceptAccount, type DeclinedAccount, declineAccount, isDeclined, } from './interlock.js';
 export { type AccountMapper, acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, type MutateVaultRosterOptions, mutateVaultRoster, type ProjectionOptions, projectVaultRoster, type QuotaReceipt, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, resolveVaultPrimary, type VaultPrimary, type VaultPrimaryBinding, type VaultPrimaryUnavailableReason, type VaultRosterFile, type VaultRosterLockContext, type VaultRosterRow, vaultRoutingRows, } from './roster.js';
+export { type ChangeNotice, ChangeNoticeReader, RESUBSCRIBE_BACKOFF_MS, SAFETY_POLL_MS, ScopedRosterWatch, type ScopedRosterWatchOptions, type ScopedWatchEnd, type ScopedWatchHandle, type ScopedWatchNoticeShape, type ScopedWatchSource, WATCH_RETRY_MS, type WatchMode, } from './watch.js';
 /**
  * Connect the client that lists and fetches this consumer's vault credentials
  * on the request path. `connectionFile` is required: this library

package/dist/internal-types/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;
@@ -43,21 +44,68 @@ 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;

package/dist/internal-types/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;
+}