@abloatai/ablo 0.25.0 → 0.27.0

package/dist/sync/createClaimStream.js

@@ -1,34 +1,42 @@
 /**
- * Transport-driven ClaimStream factory.
+ * Creates a {@link ClaimStream} over a live sync connection. A claim is a
+ * short-lived, advisory lease a participant takes on an entity (or a field of
+ * one) to signal "I'm working on this"; the stream lets you take claims, see
+ * everyone else's, and watch the wait queue when a claim is contended.
  *
- * Mirrors `createPresenceStream` — built directly on `SyncWebSocket`,
- * no SyncAgent wrapper. Claims derive their `others` view from the
- * same `presence_update` frames the presence stream consumes (the
- * Hub piggybacks `activeClaims` on every presence frame). Outbound
- * announce/revoke ride the same socket via `claim_begin` /
+ * The stream is built directly on the sync WebSocket and shares that one
+ * connection. It learns about other participants' claims from the same
+ * `presence_update` frames the {@link createPresenceStream} presence stream
+ * consumes — the server piggybacks each participant's `activeClaims` on every
+ * presence frame — and sends its own claims as `claim_begin` and
  * `claim_abandon` frames.
  *
- * Wire contract (apps/sync-server/src/hub/types.ts):
- *   • Outbound: `{ type: 'claim_begin', payload: { claimId,
- *       entityType, entityId, reason, field?, estimatedMs? } }`
- *   • Outbound: `{ type: 'claim_abandon', payload: { claimId,
- *       entityType?, entityId? } }`
- *   • Inbound (via presence): `event.activeClaims: Claim[]`
- *     stamped with `declaredAt`, `expiresAt`.
- *   • Inbound: `claim_rejected` event with conflict metadata.
- *
- * After the dual-engine collapse (step #36), this is the only
- * ClaimStream factory in the SDK; the older compatibility path
- * deletes.
+ * Wire frames:
+ *   • Outbound `claim_begin` — announce a claim: `{ claimId, entityType,
+ *       entityId, reason, field?, estimatedMs? }`.
+ *   • Outbound `claim_abandon` — release it: `{ claimId, entityType?,
+ *       entityId? }`.
+ *   • Inbound, via presence — `event.activeClaims`, each stamped with
+ *       `declaredAt` and `expiresAt`.
+ *   • Inbound `claim_rejected` — the server refused the claim, with conflict
+ *       metadata.
  */
 import { asyncIteratorFrom } from '../utils/asyncIterator.js';
 import { toMs } from '../utils/duration.js';
-import { descriptionFromMeta, participantKindFromWire, } from '../coordination/schema.js';
+import { claimHeartbeatAckPayloadSchema, descriptionFromMeta, participantKindFromWire, } from '../coordination/schema.js';
+import { AbloClaimedError, AbloConnectionError } from '../errors.js';
+import { resolveHeartbeatOptions } from '../client/claimHeartbeatLoop.js';
 import { getContext } from '../context.js';
 /** Readable target for the coordination trace: `documents:abc` / `documents:abc.title`. */
 function claimLabel(type, id, field) {
     return field ? `${type}:${id}.${field}` : `${type}:${id}`;
 }
+/**
+ * How long a heartbeat waits for its `claim_heartbeat_ack` before giving up
+ * as transient (the auto-heartbeat loop's next tick retries). Comfortably
+ * above a round trip, comfortably below the ttl/3 beat cadence.
+ */
+const HEARTBEAT_ACK_TIMEOUT_MS = 10_000;
 export function createClaimStream(config, transport = null) {
     const { participantId } = config;
     // ── State: others' open claims, keyed by claimId ───────────────
@@ -49,6 +57,16 @@ export function createClaimStream(config, transport = null) {
     const listeners = new Set();
     const rejectionListeners = new Set();
     const lostListeners = new Set();
+    // ── State: in-flight heartbeats awaiting their ack, keyed by claimId ──
+    const pendingHeartbeats = new Map();
+    const settleHeartbeat = (claimId, settle) => {
+        const pending = pendingHeartbeats.get(claimId);
+        if (!pending)
+            return;
+        pendingHeartbeats.delete(claimId);
+        clearTimeout(pending.timer);
+        settle(pending);
+    };
     const notifyListeners = () => {
         claimsSnapshot = Object.freeze(Array.from(activeByClaimId.values()));
         for (const l of listeners) {
@@ -151,8 +169,9 @@ export function createClaimStream(config, transport = null) {
                 }
             }
         }));
-        // (2a) Server-side LOSS frames — you held it, then lost it (preempted /
-        //      expired). Distinct from a rejection (a claim the server refused).
+        // (2a) Server-side loss frames — you held the claim, then lost it
+        //      (preempted or expired). Distinct from a rejection, which is a claim
+        //      the server refused.
         unsubs.push(t.subscribe('claim_lost', (payload) => {
             const lost = payload;
             if (!lost.claimId)
@@ -186,11 +205,12 @@ export function createClaimStream(config, transport = null) {
                 queueByEntity.delete(key);
             else
                 queueByEntity.set(key, Object.freeze([...line]));
-            // If WE are in this line, trace our position (the "agent queued behind a
+            // If we are in this line, trace our position (the "agent queued behind a
             // claim" moment) — once per position change, so advancing is visible.
             const ourIndex = line.findIndex((c) => ownClaims.has(c.id));
-            if (ourIndex >= 0) {
-                const ourId = line[ourIndex].id;
+            const ourClaim = ourIndex >= 0 ? line[ourIndex] : undefined;
+            if (ourClaim) {
+                const ourId = ourClaim.id;
                 if (lastLoggedQueuePos.get(ourId) !== ourIndex) {
                     lastLoggedQueuePos.set(ourId, ourIndex);
                     getContext().logger.info(`claim: queued for ${claimLabel(p.target.type, p.target.id)} — position ${ourIndex + 1} of ${line.length}, waiting`, { claimId: ourId });
@@ -198,6 +218,30 @@ export function createClaimStream(config, transport = null) {
             }
             notifyListeners();
         }));
+        // (2c) Heartbeat replies — correlate back to the awaiting beat by
+        //      claimId. `held` resolves with the extended expiry; `queued` and
+        //      `lost` reject with a typed claimed error, because a heartbeat on
+        //      a handle we thought we held coming back as anything but `held`
+        //      means the lease is no longer ours.
+        unsubs.push(t.subscribe('claim_heartbeat_ack', (payload) => {
+            const parsed = claimHeartbeatAckPayloadSchema.safeParse(payload);
+            if (!parsed.success)
+                return;
+            const ack = parsed.data;
+            settleHeartbeat(ack.claimId, ({ resolve, reject }) => {
+                if (ack.status === 'held' && ack.expiresAt !== undefined) {
+                    resolve({
+                        expiresAt: ack.expiresAt,
+                        ...(ack.queueDepth !== undefined
+                            ? { queueDepth: ack.queueDepth }
+                            : {}),
+                    });
+                    return;
+                }
+                const c = ownClaims.get(ack.claimId);
+                reject(new AbloClaimedError(`The lease behind ${c ? claimLabel(c.entityType, c.entityId, c.field) : `claim ${ack.claimId}`} is no longer held — it expired or was granted onward while this participant was working. Re-acquire the claim and retry; a write attempted under the old lease is rejected by its \`readAt\` guard.`, { code: 'claim_lost' }));
+            });
+        }));
         // (3) On reconnect, re-announce every open self-claim — the
         //     server's claim state is in-memory and is lost across
         //     restarts. Without this, peers would see our claims vanish
@@ -244,6 +288,39 @@ export function createClaimStream(config, transport = null) {
             },
         });
     }
+    /**
+     * Send one heartbeat and await its ack. Rejects with
+     * {@link AbloConnectionError} (transient — the auto-heartbeat loop retries
+     * on its next tick) when the socket is down or the ack times out, and with
+     * {@link AbloClaimedError} (definitive) when the server answers that the
+     * lease is no longer ours.
+     */
+    function sendHeartbeat(claimId, claim, options) {
+        if (!attached?.isConnected()) {
+            return Promise.reject(new AbloConnectionError(`The heartbeat for ${claimLabel(claim.entityType, claim.entityId, claim.field)} was skipped because the connection is down. The keepalive renews held leases automatically on reconnect; the next beat retries.`));
+        }
+        return new Promise((resolve, reject) => {
+            settleHeartbeat(claimId, ({ reject: rejectPrior }) => {
+                rejectPrior(new AbloConnectionError('A newer heartbeat for this claim superseded the one still awaiting its reply.'));
+            });
+            const timer = setTimeout(() => {
+                settleHeartbeat(claimId, ({ reject: rejectTimeout }) => {
+                    rejectTimeout(new AbloConnectionError(`No reply to the heartbeat for ${claimLabel(claim.entityType, claim.entityId, claim.field)} arrived within ${HEARTBEAT_ACK_TIMEOUT_MS / 1000}s. The next beat retries.`));
+                });
+            }, HEARTBEAT_ACK_TIMEOUT_MS);
+            pendingHeartbeats.set(claimId, { resolve, reject, timer });
+            attached?.send({
+                type: 'claim_heartbeat',
+                payload: {
+                    claimId,
+                    entityType: claim.entityType,
+                    entityId: claim.entityId,
+                    ...(options.ttl !== undefined ? { ttlMs: toMs(options.ttl) } : {}),
+                    ...(options.details !== undefined ? { details: options.details } : {}),
+                },
+            });
+        });
+    }
     function sendAbandon(claimId, claim) {
         if (!attached?.isConnected())
             return;
@@ -280,7 +357,7 @@ export function createClaimStream(config, transport = null) {
         };
         ownClaims.set(claimId, claim);
         sendBegin(claimId, claim);
-        // Coordination trace (info): the creator can SEE their human/agent claims.
+        // Coordination trace (info): the creator can see their human/agent claims.
         getContext().logger.info(`claim: requesting ${claimLabel(claim.entityType, claim.entityId, claim.field)} for "${claim.reason}"` +
             (claim.queue ? ' (will queue if contended)' : ''), { claimId });
         let revoked = false;
@@ -309,6 +386,7 @@ export function createClaimStream(config, transport = null) {
                 revoke();
             },
             revoke,
+            heartbeat: (options) => sendHeartbeat(claimId, claim, resolveHeartbeatOptions(options)),
             [Symbol.asyncDispose]: async () => {
                 revoke();
             },
@@ -376,6 +454,11 @@ export function createClaimStream(config, transport = null) {
             for (const off of unsubs)
                 off();
             unsubs.length = 0;
+            for (const claimId of [...pendingHeartbeats.keys()]) {
+                settleHeartbeat(claimId, ({ reject }) => {
+                    reject(new AbloConnectionError('The claim stream was disposed while this heartbeat was awaiting its reply.'));
+                });
+            }
             listeners.clear();
             rejectionListeners.clear();
             lostListeners.clear();

package/dist/sync/createPresenceStream.d.ts

@@ -1,25 +1,26 @@
 /**
- * Transport-driven PresenceStream factory.
+ * Creates a {@link PresenceStream} over a live sync connection. Presence is the
+ * lightweight, ephemeral "who's here and what are they doing" view: each
+ * participant broadcasts a status and an activity, and sees everyone else's.
+ * The stream is built directly on the sync WebSocket and adds no second
+ * connection. It is the sibling of {@link createClaimStream}, which reuses the
+ * same presence frames.
  *
- * This is the engine's home for presence — built directly on
- * `SyncWebSocket`, no SyncAgent wrapper, no second connection. The
- * older compatibility path predates this and will be deleted when
- * the dual-engine collapse completes.
+ * There are two ways to construct it:
  *
- * Two construction modes:
+ *   1. Direct — pass an already-open `transport`, for example an agent worker
+ *      or a test.
+ *   2. Deferred — construct without a transport and call `attach(transport)`
+ *      once the connection is ready. The returned stream object is stable from
+ *      construction, so callers can hold the reference and let attachment
+ *      happen later.
  *
- *   1. Direct — pass `transport: SyncWebSocket` when it's already
- *      open (agent worker, tests).
- *   2. Deferred — pass `attachLater: true` and call `.attach(transport)`
- *      once the engine's WS lifecycle has produced one. The returned
- *      stream object is stable from construction; attachment can
- *      happen later without callers having to re-grab the reference.
- *
- * Wire contract (apps/sync-server/src/hub/types.ts):
- *   • Outbound: `{ type: 'presence_update', payload: { status, activity? } }`
- *     — server stamps `userId`, `kind`, `timestamp`, `isAgent` and
- *       broadcasts to other clients on the same sync groups.
- *   • Inbound:  same frame, with `kind: 'enter' | 'update' | 'leave'`.
+ * Wire frames:
+ *   • Outbound `presence_update` — `{ status, activity? }`. The server stamps
+ *       `userId`, `kind`, `timestamp`, and `isAgent`, then broadcasts to the
+ *       other participants on the same sync groups.
+ *   • Inbound — the same frame, with `kind` one of `enter`, `update`, or
+ *       `leave`.
  */
 import type { SyncWebSocket } from './SyncWebSocket.js';
 import type { PresenceStream } from '../types/streams.js';

package/dist/sync/createPresenceStream.js

@@ -1,25 +1,26 @@
 /**
- * Transport-driven PresenceStream factory.
+ * Creates a {@link PresenceStream} over a live sync connection. Presence is the
+ * lightweight, ephemeral "who's here and what are they doing" view: each
+ * participant broadcasts a status and an activity, and sees everyone else's.
+ * The stream is built directly on the sync WebSocket and adds no second
+ * connection. It is the sibling of {@link createClaimStream}, which reuses the
+ * same presence frames.
  *
- * This is the engine's home for presence — built directly on
- * `SyncWebSocket`, no SyncAgent wrapper, no second connection. The
- * older compatibility path predates this and will be deleted when
- * the dual-engine collapse completes.
+ * There are two ways to construct it:
  *
- * Two construction modes:
+ *   1. Direct — pass an already-open `transport`, for example an agent worker
+ *      or a test.
+ *   2. Deferred — construct without a transport and call `attach(transport)`
+ *      once the connection is ready. The returned stream object is stable from
+ *      construction, so callers can hold the reference and let attachment
+ *      happen later.
  *
- *   1. Direct — pass `transport: SyncWebSocket` when it's already
- *      open (agent worker, tests).
- *   2. Deferred — pass `attachLater: true` and call `.attach(transport)`
- *      once the engine's WS lifecycle has produced one. The returned
- *      stream object is stable from construction; attachment can
- *      happen later without callers having to re-grab the reference.
- *
- * Wire contract (apps/sync-server/src/hub/types.ts):
- *   • Outbound: `{ type: 'presence_update', payload: { status, activity? } }`
- *     — server stamps `userId`, `kind`, `timestamp`, `isAgent` and
- *       broadcasts to other clients on the same sync groups.
- *   • Inbound:  same frame, with `kind: 'enter' | 'update' | 'leave'`.
+ * Wire frames:
+ *   • Outbound `presence_update` — `{ status, activity? }`. The server stamps
+ *       `userId`, `kind`, `timestamp`, and `isAgent`, then broadcasts to the
+ *       other participants on the same sync groups.
+ *   • Inbound — the same frame, with `kind` one of `enter`, `update`, or
+ *       `leave`.
  */
 import { asyncIteratorFrom } from '../utils/asyncIterator.js';
 import { participantKindFromWire } from '../coordination/schema.js';
@@ -67,10 +68,9 @@ export function createPresenceStream(config, transport = null) {
             if (self.activity.entityId)
                 sendUpdate(self.activity);
         }));
-        // Inbound presence frames — translate the legacy wire vocabulary
-        // (userId / isAgent / timestamp) into the engine shape
-        // (participantId / participantKind / lastActive). When the server
-        // adopts the engine names this block collapses to a pass-through.
+        // Inbound presence frames arrive in the wire vocabulary
+        // (userId / isAgent / timestamp); translate them into the shape this
+        // stream exposes (participantId / participantKind / lastActive).
         unsubs.push(t.subscribe('presence_update', (event) => {
             if (event.userId === participantId)
                 return; // own echo
@@ -117,10 +117,9 @@ export function createPresenceStream(config, transport = null) {
     if (transport)
         attach(transport);
     // ── Outbound ────────────────────────────────────────────────────
-    // Note: do NOT include `isAgent` in the payload. Server derives it
-    // authoritatively from the connection's identity prefix; clients
-    // self-declaring `isAgent` caused human sessions to broadcast as
-    // agents to peers (real bug we caught earlier).
+    // Do not include `isAgent` in the payload. The server derives it
+    // authoritatively from the connection's identity, and letting a client
+    // self-declare it once caused human sessions to broadcast as agents to peers.
     function sendUpdate(activity) {
         if (!attached?.isConnected())
             return; // no-op until connected

package/dist/sync/createSnapshot.d.ts

@@ -1,24 +1,22 @@
 /**
- * Engine-attached snapshot factory.
+ * Captures a {@link Snapshot} of a chosen set of entities, along with a
+ * watermark, so a caller can detect when that state has gone stale. This is
+ * what an LLM caller threads into a prompt: `stamp` flows into later writes as
+ * `readAt`, so the server rejects a mutation premised on data that has since
+ * changed; `signal` is an `AbortSignal` that fires as soon as any captured
+ * entity receives a delta, so a mid-generation invalidation can abort the token
+ * stream instead of producing output against stale context.
  *
- * Captures the engine's current entity state + watermark for context-
- * staleness detection. The returned Snapshot is what an LLM caller
- * threads into a prompt: `stamp` flows into writes as `readAt` so the
- * server rejects mutations against now-stale data; `signal` fires on
- * any captured-entity delta so mid-generation invalidations abort
- * the token stream rather than producing output against dead context.
- *
- * Reads from the engine's MobX-reactive ObjectPool, picks up the
- * engine's `lastSyncId`, and subscribes to delta frames on the
- * engine's transport. Same socket as entity sync — no second
- * connection.
+ * It reads the current entity state from the in-memory pool, reads the engine's
+ * current `lastSyncId` as the watermark, and subscribes to delta frames on the
+ * existing sync connection — no second connection.
  */
-import type { ObjectPool } from '../ObjectPool.js';
+import type { InstanceCache } from '../InstanceCache.js';
 import type { Schema } from '../schema/schema.js';
 import type { SyncWebSocket } from './SyncWebSocket.js';
 import type { Snapshot } from '../types/streams.js';
 export interface CreateSnapshotArgs<TSchema extends Schema = Schema, K extends keyof TSchema['models'] & string = keyof TSchema['models'] & string> {
-    pool: ObjectPool;
+    pool: InstanceCache;
     /** Live transport for delta subscriptions. May be null if the engine
      *  hasn't connected yet — the snapshot still resolves with current
      *  pool state, but `signal` won't fire until reconnect. */
@@ -26,8 +24,6 @@ export interface CreateSnapshotArgs<TSchema extends Schema = Schema, K extends k
     /** Returns the engine's current `lastSyncId`. Read at snapshot time
      *  to stamp the watermark; not re-read after. */
     getLastSyncId: () => number;
-    entities: {
-        readonly [M in K]: string | readonly string[];
-    };
+    entities: Readonly<Record<K, string | readonly string[]>>;
 }
 export declare function createSnapshot<TSchema extends Schema, K extends keyof TSchema['models'] & string>(args: CreateSnapshotArgs<TSchema, K>): Snapshot<TSchema, K>;

package/dist/sync/createSnapshot.js

@@ -1,24 +1,22 @@
 /**
- * Engine-attached snapshot factory.
+ * Captures a {@link Snapshot} of a chosen set of entities, along with a
+ * watermark, so a caller can detect when that state has gone stale. This is
+ * what an LLM caller threads into a prompt: `stamp` flows into later writes as
+ * `readAt`, so the server rejects a mutation premised on data that has since
+ * changed; `signal` is an `AbortSignal` that fires as soon as any captured
+ * entity receives a delta, so a mid-generation invalidation can abort the token
+ * stream instead of producing output against stale context.
  *
- * Captures the engine's current entity state + watermark for context-
- * staleness detection. The returned Snapshot is what an LLM caller
- * threads into a prompt: `stamp` flows into writes as `readAt` so the
- * server rejects mutations against now-stale data; `signal` fires on
- * any captured-entity delta so mid-generation invalidations abort
- * the token stream rather than producing output against dead context.
- *
- * Reads from the engine's MobX-reactive ObjectPool, picks up the
- * engine's `lastSyncId`, and subscribes to delta frames on the
- * engine's transport. Same socket as entity sync — no second
- * connection.
+ * It reads the current entity state from the in-memory pool, reads the engine's
+ * current `lastSyncId` as the watermark, and subscribes to delta frames on the
+ * existing sync connection — no second connection.
  */
 import { AbloValidationError } from '../errors.js';
 import { Model, modelAsRow } from '../Model.js';
 /**
- * Three top-level keys that conflict with the per-model buckets if a
- * customer's schema declares a model named `stamp` / `signal` /
- * `onChange`. Throw at snapshot time so the collision is loud.
+ * The snapshot result exposes `stamp`, `signal`, and `onChange` at its top
+ * level, alongside one bucket per model. If a schema declares a model with one
+ * of these names, the two would collide, so snapshot creation throws instead.
  */
 const RESERVED_SNAPSHOT_KEYS = new Set([
     'stamp',
@@ -80,9 +78,7 @@ export function createSnapshot(args) {
             const key = `${delta.modelName}:${delta.modelId}`;
             if (!watched.has(key))
                 return;
-            // The snapshot API treats every delta as 'semantic' severity.
-            // Future: distinguish metadata-only deltas (e.g., updatedAt
-            // bumps) from content changes — that's a separate scope.
+            // Every delta to a captured entity is reported as 'semantic' severity.
             fireChange({
                 model: delta.modelName,
                 id: delta.modelId,
@@ -96,16 +92,14 @@ export function createSnapshot(args) {
         signal: controller.signal,
         onChange: (listener) => {
             listeners.add(listener);
-            // Caller is responsible for unsubscribing when they're done.
-            // The delta subscription itself stays for the snapshot's life;
-            // there's no public dispose because snapshots are short-lived
-            // (one LLM call's worth) and the transport-level subscription
-            // is cheap. If a long-lived consumer needs explicit teardown,
-            // we can add `.dispose()` in a follow-up.
+            // The caller unsubscribes its own listener via the returned function.
+            // The underlying delta subscription lives for the snapshot's lifetime;
+            // there is no explicit dispose because a snapshot is short-lived (one
+            // LLM call's worth) and the subscription is cheap.
             return () => {
                 listeners.delete(listener);
-                // If the last listener AND the abort fired, drop the delta
-                // subscription too — no one's listening anymore.
+                // Once the last listener is gone and the abort has fired, drop the
+                // delta subscription too — nothing is listening anymore.
                 if (listeners.size === 0 && controller.signal.aborted && unsubDelta) {
                     unsubDelta();
                     unsubDelta = null;

package/dist/sync/credentialLifecycle.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Keeps the short-lived access credential fresh. It owns the re-mint hook, a
+ * single-flight guard that stops concurrent triggers from minting more than
+ * once, and a browser-only proactive refresh — a timer plus an OS-wake listener
+ * — that renews the credential ahead of expiry. It reaches the rest of the
+ * client only through the small {@link CredentialLifecycleContext} interface,
+ * so the two can reference each other without an import cycle.
+ */
+import type { RecoveryClass } from '../errorCodes.js';
+/**
+ * Tri-state outcome of a credential re-mint, mirroring the `getToken`
+ * contract (see {@link CredentialLifecycle.refresh}).
+ */
+export type CredentialRefreshOutcome = 'refreshed' | 'session_error' | 'network_error';
+/**
+ * What an auth-rejected transport should do after recovery has run. `'retry'`
+ * means a fresh credential is now in place — replay the request once. `'stop'`
+ * means don't replay: either the session is gone for good, the rejection is one
+ * a re-mint can't cure, or the mint failed transiently and the caller's own
+ * retry path will recover later.
+ */
+export type CredentialRecoveryOutcome = 'retry' | 'stop';
+/**
+ * What a credential refresher may resolve with. The plain-string form returns
+ * just the token. The object form also carries the mint response's `expiresAt`
+ * (an ISO string, epoch milliseconds, or a `Date`), which lets the proactive
+ * pre-roll schedule against the credential's real lifetime rather than assume
+ * the server's default expiry.
+ */
+export type CredentialRefreshResult = string | {
+    readonly token: string;
+    readonly expiresAt?: string | number | Date;
+} | null;
+/** A credential re-mint hook. `Promise<string | null>` resolvers remain
+ *  assignable — the widened result type is a superset. */
+export type CredentialRefresher = () => Promise<CredentialRefreshResult>;
+/** The fallback pre-roll interval, and also its ceiling: 10 minutes, which sits
+ *  comfortably inside the server's 15-minute default credential lifetime. Used
+ *  as-is when the refresher reports no expiry. */
+export declare const DEFAULT_PREROLL_INTERVAL_MS: number;
+/** Floor so a very short (or already-elapsed) TTL can't hot-loop the mint. */
+export declare const MIN_PREROLL_DELAY_MS: number;
+/**
+ * Computes how long to wait before pre-rolling a credential that expires at
+ * `expiresAtMs`: about two-thirds of the remaining lifetime (a 15-minute
+ * credential yields 10 minutes), clamped to
+ * [{@link MIN_PREROLL_DELAY_MS}, {@link DEFAULT_PREROLL_INTERVAL_MS}]. An
+ * unknown expiry (`null`) falls back to the 10-minute interval. Exported for
+ * unit tests.
+ */
+export declare function computePrerollDelayMs(expiresAtMs: number | null, nowMs: number): number;
+/**
+ * The callbacks this lifecycle needs back from the surrounding client. It is
+ * deliberately minimal — three callbacks, each resolved lazily at call time,
+ * because the connection machinery behind two of them isn't constructed until
+ * the sync connection is set up.
+ */
+export interface CredentialLifecycleContext {
+    /** Push a freshly-minted access token into the shared credential source
+     *  (no-op when the deployment wired no credential source). */
+    setAuthToken(token: string): void;
+    /** Nudge the connection to re-probe using the credential now in place. */
+    nudgeReconnect(): void;
+    /** Report that the long-lived login is gone, so the connection can move to
+     *  its signed-out state. */
+    reportSessionExpired(): void;
+}
+export declare class CredentialLifecycle {
+    private readonly ctx;
+    /**
+     * The hook that mints a fresh short-lived access credential (the `ek_`/`rk_`
+     * key). An integrator wires it from their own token endpoint: this lifecycle
+     * decides when to refresh (a stale-credential probe or an external nudge),
+     * and the hook decides how to mint. It follows the same contract as a
+     * `getToken` function — it resolves a token string on success, `null` when
+     * the long-lived login is gone (a terminal state), and throws on a transient
+     * or offline failure. Used by {@link refresh}. When it is absent there is no
+     * silent re-mint, as with a static `apiKey` whose credential source is
+     * refreshed elsewhere.
+     */
+    private credentialRefresher;
+    /** Single-flight guard so a wake nudge + an in-flight request + a probe don't
+     *  all mint at once (the classic "token thrash → random logout" bug). */
+    private inFlightCredentialRefresh;
+    /** Tears down the proactive credential lifecycle (the refresh timer and the
+     *  OS-wake listener) installed by {@link start}; cleared when the client
+     *  disconnects. Null when no refresher is wired. */
+    private credentialLifecycleTeardown;
+    /** Epoch milliseconds at which the current credential expires, when the
+     *  refresher reports it (the object form of {@link CredentialRefreshResult}).
+     *  `null` for the string-form resolver, in which case the pre-roll uses its
+     *  fixed interval. */
+    private credentialExpiresAtMs;
+    /** Re-arms the proactive pre-roll timer (set by {@link start}). Called after
+     *  every successful mint, so a refresh triggered reactively (by a probe, an
+     *  OS wake, or the first mint) re-anchors the schedule to the fresh
+     *  credential's real expiry instead of a stale fixed delay. */
+    private prerollReschedule;
+    constructor(ctx: CredentialLifecycleContext);
+    /**
+     * Registers the re-mint hook for the access credential — a function that
+     * mints a fresh `ek_`/`rk_` key, typically the integrator's `getToken`. See
+     * {@link credentialRefresher}.
+     */
+    setRefresher(refresher: CredentialRefresher | null): void;
+    /**
+     * Re-mints the short-lived access credential, pushes it into the credential
+     * source, and reports a three-way outcome the connection layer acts on:
+     *   - a token string → `'refreshed'`     (the fresh key is in place; re-probe and reconnect)
+     *   - `null`         → `'session_error'` (the login itself is gone — terminal, sign out)
+     *   - a thrown error → `'network_error'` (the mint endpoint was unreachable — transient)
+     *
+     * The call is single-flight: concurrent triggers (an OS wake, an in-flight
+     * request, a probe) share one in-flight promise, so the credential is never
+     * minted twice at once. This avoids the failure where every rejected request
+     * mints a new token and the resulting thrash logs the user out.
+     *
+     * With no refresher wired, it resolves `'refreshed'` as a no-op re-probe: a
+     * static-`apiKey` client has no session to mint from and its credential
+     * source is refreshed elsewhere, so it simply re-probes with what it holds.
+     */
+    refresh(): Promise<CredentialRefreshOutcome>;
+    /**
+     * Interprets a refresh outcome and drives the connection accordingly. This is
+     * the single place the three-way outcome is acted on, shared by the proactive
+     * pre-roll, the OS-wake nudge, and the HTTP auth-recovery path, so every
+     * trigger converges on the same behavior.
+     */
+    private routeRefreshOutcome;
+    /**
+     * The shared recovery path for a request rejected on authentication, over any
+     * transport. The WebSocket probe already routes its own 401s; HTTP callers
+     * call this instead of inventing their own handling, so every path shares one
+     * single-flight mint, one outcome routing, and one taxonomy. It classifies
+     * the same recovery codes the connection probe does:
+     *   - `access_credential_expiry` — the routine case, an expired `ek_`/`rk_`:
+     *     silently re-mint through the single-flight {@link refresh} and tell the
+     *     caller to replay once on success. This never signs out on its own; the
+     *     only terminal path is the mint resolving `null`.
+     *   - `session_expiry` — the login is gone: report it (which drives sign-out)
+     *     and stop, since replaying is pointless.
+     *   - `auth_blocked`, `permission`, and everything else — re-minting would
+     *     produce the same rejected credential, so stop and leave the connection
+     *     alone.
+     */
+    recoverFromAuthRejection(recovery: RecoveryClass): Promise<CredentialRecoveryOutcome>;
+    /**
+     * Installs the credential lifecycle. It has two parts:
+     *   1. Reactive — registers `getToken` as the re-mint hook the connection
+     *      calls when a probe finds the key stale, or on a nudge.
+     *   2. Proactive — keeps the short-lived key fresh ahead of expiry with a
+     *      refresh timer inside the credential's lifetime, plus a re-mint on OS
+     *      wake. The whole proactive block is browser-gated on `typeof window`,
+     *      because a server render has no socket to keep warm and the resolver is
+     *      browser-oriented; arming it under Node would fire a relative-URL fetch
+     *      and throw. (Agents pass a static `apiKey` with no resolver, so this
+     *      method is never called for them.)
+     *
+     * Refreshing is automatic — a consumer never calls a refresh method. The call
+     * is idempotent: a second call replaces the first, and it is torn down when
+     * the client disconnects.
+     *
+     * `opts.proactiveInNode` arms the refresh timer on a windowless host as well.
+     * Set it for agent or system participants — long-lived server sockets whose
+     * `rk_`/`ek_` must renew before the server's keepalive check closes them.
+     * Node timers are `unref`ed, so a finishing script is never held alive by the
+     * pre-roll. The OS-wake listener stays browser-only regardless, since there
+     * is no `window` to listen on.
+     */
+    start(getToken: CredentialRefresher, opts?: {
+        proactiveInNode?: boolean;
+    }): void;
+    /** Tear down the proactive credential lifecycle (idempotent). */
+    stop(): void;
+}