@abloatai/ablo 0.25.0 → 0.27.0

package/dist/SyncEngineContext.d.ts

@@ -4,7 +4,7 @@
  * All SDK classes receive this context at construction time.
  * It bundles every injectable dependency so constructors stay clean.
  */
-import type { SyncLogger, SyncObservabilityProvider, SyncAnalytics, SessionErrorDetector, OnlineStatusProvider, ModelDebugLoggerContract, MutationExecutor, MutationDispatcher, SyncEngineConfig } from './interfaces/index.js';
+import type { SyncLogger, SyncObservabilityProvider, SyncAnalytics, SessionErrorDetector, OnlineStatusProvider, ModelDebugLoggerContract, MutationExecutor, SyncEngineConfig } from './interfaces/index.js';
 export interface SyncEngineContext {
     /** Structured logger */
     logger: SyncLogger;
@@ -20,8 +20,6 @@ export interface SyncEngineContext {
     modelDebugLogger?: ModelDebugLoggerContract;
     /** Backend mutation transport (GraphQL, REST, etc.) */
     mutationExecutor: MutationExecutor;
-    /** Offline mutation replay dispatcher */
-    mutationDispatcher: MutationDispatcher;
     /** Application-specific sync configuration */
     config: SyncEngineConfig;
 }

package/dist/SyncEngineContext.js

@@ -26,7 +26,6 @@ export const noopObservability = {
     captureReconciliation() { },
     captureDeltaRetryExhausted() { },
     captureWebSocketError() { },
-    captureOfflineFlushFailure() { },
     captureSelfHealing() { },
     captureClaim() { },
     captureConflict() { },
@@ -57,7 +56,7 @@ export const browserOnlineStatus = {
 export const defaultSessionErrorDetector = {
     isSessionError(error) {
         if (error && typeof error === 'object' && 'isSessionError' in error) {
-            return error.isSessionError === true;
+            return error.isSessionError;
         }
         return false;
     },

package/dist/adapters/alwaysOnline.d.ts

@@ -1,12 +1,10 @@
 /**
- * Always-online network provider — for Node.js / agent / sidecar.
- *
- * The server IS the network — it doesn't go offline. If the Postgres
- * connection drops, that's a database error, not a network error.
- * The "online/offline" concept only applies to browser clients that
- * can lose their WiFi connection.
- *
- * Implements OnlineStatusProvider (same interface as browserOnlineStatus).
+ * An {@link OnlineStatusProvider} that always reports the client as online.
+ * Server-side runtimes — Node processes, agents, and sidecars — have no
+ * browser network stack to lose, so there is no offline state to track. A
+ * dropped database connection surfaces as a database error, not a network
+ * transition. This is the server-side counterpart to the browser's
+ * connectivity-aware provider, which watches the real online/offline signal.
  */
 import type { OnlineStatusProvider } from '../interfaces/index.js';
 /**

package/dist/adapters/alwaysOnline.js

@@ -1,12 +1,10 @@
 /**
- * Always-online network provider — for Node.js / agent / sidecar.
- *
- * The server IS the network — it doesn't go offline. If the Postgres
- * connection drops, that's a database error, not a network error.
- * The "online/offline" concept only applies to browser clients that
- * can lose their WiFi connection.
- *
- * Implements OnlineStatusProvider (same interface as browserOnlineStatus).
+ * An {@link OnlineStatusProvider} that always reports the client as online.
+ * Server-side runtimes — Node processes, agents, and sidecars — have no
+ * browser network stack to lose, so there is no offline state to track. A
+ * dropped database connection surfaces as a database error, not a network
+ * transition. This is the server-side counterpart to the browser's
+ * connectivity-aware provider, which watches the real online/offline signal.
  */
 /**
  * Returns an OnlineStatusProvider that always reports online.

package/dist/adapters/inMemoryStorage.d.ts

@@ -1,14 +1,14 @@
 /**
- * In-memory storage adapter — replaces IndexedDB for Node.js / agent / test.
+ * An in-memory {@link ObjectStoreContract} implementation for runtimes
+ * without IndexedDB, such as Node processes, agents, and tests. It keeps
+ * records in a map and maintains simple secondary indexes, satisfying the
+ * same contract the IndexedDB-backed store implements — so if the two ever
+ * diverge, the mismatch becomes a typecheck error here rather than a silent
+ * failure at a call site.
  *
- * Implements {@link ObjectStoreContract}, the shared surface that
- * IDB-backed `ObjectStore` also satisfies. Centralized contract so a
- * future drift between the two trips a typecheck error here, not
- * silently in a caller.
- *
- * No persistence — cleared on process restart. This is intentional:
- * the Node sync-server and agent workers get their state from the
- * server's delta stream, not from a local cache.
+ * Nothing is persisted; the data is cleared on process restart. That is
+ * deliberate: server-side runtimes and agent workers rebuild their state from
+ * the server's delta stream rather than from a local cache.
  */
 import type { ObjectStoreContract } from '../stores/ObjectStoreContract.js';
 export declare class InMemoryObjectStore implements ObjectStoreContract {

package/dist/adapters/inMemoryStorage.js

@@ -1,14 +1,14 @@
 /**
- * In-memory storage adapter — replaces IndexedDB for Node.js / agent / test.
+ * An in-memory {@link ObjectStoreContract} implementation for runtimes
+ * without IndexedDB, such as Node processes, agents, and tests. It keeps
+ * records in a map and maintains simple secondary indexes, satisfying the
+ * same contract the IndexedDB-backed store implements — so if the two ever
+ * diverge, the mismatch becomes a typecheck error here rather than a silent
+ * failure at a call site.
  *
- * Implements {@link ObjectStoreContract}, the shared surface that
- * IDB-backed `ObjectStore` also satisfies. Centralized contract so a
- * future drift between the two trips a typecheck error here, not
- * silently in a caller.
- *
- * No persistence — cleared on process restart. This is intentional:
- * the Node sync-server and agent workers get their state from the
- * server's delta stream, not from a local cache.
+ * Nothing is persisted; the data is cleared on process restart. That is
+ * deliberate: server-side runtimes and agent workers rebuild their state from
+ * the server's delta stream rather than from a local cache.
  */
 export class InMemoryObjectStore {
     modelName;

package/dist/agent/Agent.d.ts

@@ -45,14 +45,11 @@ import { createAgentSession } from './session.js';
 export type { AgentContext } from './types.js';
 export type { WireClaim } from '../types/streams.js';
 /**
- * Shape returned by the sync server's REST `/api/presence` endpoint.
- *
- * Local to this module, NOT exported. The server still speaks the
- * legacy vocabulary (`userId`, `isAgent`, `updatedAt`); the engine has
- * moved on to `participantId` / `participantKind` / `lastActive`.
- * `gather()` returns this shape verbatim today; once the server
- * adopts the engine names this interface deletes and the response is
- * typed as the canonical `Peer`.
+ * The record shape the sync server returns from its REST `/api/presence`
+ * endpoint. This interface is internal to this module and not exported. Its
+ * field names (`userId`, `isAgent`, `updatedAt`) are the wire contract the
+ * presence API sends, and {@link Agent.gather} surfaces these records
+ * unchanged in the `presence` array of its snapshot.
  */
 interface WirePeer {
     userId: string;
@@ -125,11 +122,10 @@ export interface FreshnessCheck {
     /** Human-readable summary — feed this back to the LLM when stale. */
     summary?: string;
     /**
-     * Pending-mutation claims from OTHER participants targeting this
-     * entity (self-claims filtered out). Empty = no one else is
-     * currently generating against this entity. Non-empty is ADVISORY
-     * — the agent can proceed, wait, or defer. Stale-read protection
-     * that predates committed deltas.
+     * Pending-mutation claims from other participants targeting this
+     * entity, with the agent's own claims filtered out. An empty array
+     * means no one else is currently generating against the entity. A
+     * non-empty array is advisory: the agent can proceed, wait, or defer.
      */
     pendingClaims?: WireClaim[];
 }
@@ -141,14 +137,14 @@ export interface AgentMessage {
 /** Subset of AI SDK's prepareStep context. */
 export interface PrepareStepContext<M extends AgentMessage = AgentMessage> {
     stepNumber: number;
-    steps: ReadonlyArray<{
-        toolCalls?: ReadonlyArray<{
+    steps: readonly {
+        toolCalls?: readonly {
             toolName: string;
             input?: unknown;
             args?: unknown;
-        }>;
-        toolResults?: ReadonlyArray<unknown>;
-    }>;
+        }[];
+        toolResults?: readonly unknown[];
+    }[];
     messages: M[];
     model?: unknown;
 }
@@ -164,12 +160,12 @@ export interface StepFinishContext {
     stepType?: 'initial' | 'continue' | 'tool-result';
     finishReason?: string;
     text?: string;
-    toolCalls?: ReadonlyArray<{
+    toolCalls?: readonly {
         toolName: string;
         input?: unknown;
         args?: unknown;
-    }>;
-    toolResults?: ReadonlyArray<unknown>;
+    }[];
+    toolResults?: readonly unknown[];
     usage?: {
         inputTokens?: number;
         outputTokens?: number;
@@ -230,6 +226,19 @@ export interface WrapToolOptions<TArgs> {
      */
     announceOnExecute?: boolean;
 }
+/**
+ * The console-backed logger an {@link Agent} uses when the caller does not
+ * supply one. It is the same gated factory the `Ablo()` client uses
+ * (`createConsoleLogger`), reads its threshold from the `ABLO_LOG_LEVEL`
+ * environment variable (default `warn`), and tags each line with `[agent]` so
+ * agent-runtime output is easy to spot. The level is resolved when the logger
+ * is built rather than at module load, so an `ABLO_LOG_LEVEL` that the host
+ * process sets before constructing an Agent is honored.
+ *
+ * Exported so a unit test can pin the gating behavior; consumers normally pass
+ * their own `logger` option instead.
+ */
+export declare function defaultAgentLogger(): SyncLogger;
 export declare class Agent implements PresenceAnnouncer {
     private readonly opts;
     constructor(options: AgentOptions);
@@ -239,11 +248,10 @@ export declare class Agent implements PresenceAnnouncer {
      * tokens before TTL elapses. Use on the server when the same agent
      * identity handles many requests.
      *
-     * Returns the cache, NOT an `Agent` instance: the long-lived path
-     * uses `Ablo({kind:'agent'})` over WebSocket, while the `Agent` class
-     * itself is the short-lived REST helper for AI SDK tool loops. The
-     * static method lives here so consumers reach for everything
-     * agent-related under one namespace.
+     * Returns the cache rather than an `Agent` instance: the long-lived path
+     * uses `Ablo({kind:'agent'})` over a WebSocket, while the `Agent` class
+     * itself is the short-lived REST helper for AI SDK tool loops. The static
+     * method lives here so everything agent-related sits under one namespace.
      *
      * ```ts
      * const session = Agent.session({ syncServerUrl, schema, issueToken });
@@ -255,8 +263,8 @@ export declare class Agent implements PresenceAnnouncer {
     get userId(): string;
     /**
      * Extract the Agent instance from an AI SDK tool's
-     * `experimental_context`. Use inside tool `execute` functions to reach
-     * the perception without closure-capturing it.
+     * `experimental_context`. Use it inside a tool's `execute` function to
+     * reach the agent without capturing it in a closure.
      *
      * ```ts
      * execute: async (args, { experimental_context }) => {
@@ -272,9 +280,9 @@ export declare class Agent implements PresenceAnnouncer {
      */
     static fromContext(ctx: unknown, toolName?: string): Agent;
     /**
-     * Narrower variant of {@link fromContext} that returns `undefined` instead
-     * of throwing when perception isn't in context. Useful for tools where
-     * awareness is optional (e.g., read-only tools that work without it).
+     * A lenient variant of {@link fromContext} that returns `undefined` instead
+     * of throwing when no agent is present in the context. Useful for tools
+     * where awareness is optional, such as read-only tools that work without it.
      */
     static tryFromContext(ctx: unknown): Agent | undefined;
     /**

package/dist/agent/Agent.js

@@ -40,17 +40,30 @@
  * for custom integrations outside the AI SDK.
  */
 import { createAgentSession } from './session.js';
+import { createConsoleLogger, resolveLogLevel } from '../client/consoleLogger.js';
 import { AbloValidationError } from '../errors.js';
 // ── Agent ───────────────────────────────────────────────────────
-// Console-backed default logger. Local to this module so the agent
-// SDK doesn't take a transitive dependency on `getContext()` (which
-// belongs to the web-app context, not standalone agent workers).
-const consoleLogger = {
-    debug: (msg, ...args) => console.debug('[agent]', msg, ...args),
-    info: (msg, ...args) => console.info('[agent]', msg, ...args),
-    warn: (msg, ...args) => console.warn('[agent]', msg, ...args),
-    error: (msg, ...args) => console.error('[agent]', msg, ...args),
-};
+/**
+ * The console-backed logger an {@link Agent} uses when the caller does not
+ * supply one. It is the same gated factory the `Ablo()` client uses
+ * (`createConsoleLogger`), reads its threshold from the `ABLO_LOG_LEVEL`
+ * environment variable (default `warn`), and tags each line with `[agent]` so
+ * agent-runtime output is easy to spot. The level is resolved when the logger
+ * is built rather than at module load, so an `ABLO_LOG_LEVEL` that the host
+ * process sets before constructing an Agent is honored.
+ *
+ * Exported so a unit test can pin the gating behavior; consumers normally pass
+ * their own `logger` option instead.
+ */
+export function defaultAgentLogger() {
+    const gated = createConsoleLogger(resolveLogLevel());
+    return {
+        debug: (msg, ...args) => { gated.debug('[agent]', msg, ...args); },
+        info: (msg, ...args) => { gated.info('[agent]', msg, ...args); },
+        warn: (msg, ...args) => { gated.warn('[agent]', msg, ...args); },
+        error: (msg, ...args) => { gated.error('[agent]', msg, ...args); },
+    };
+}
 export class Agent {
     opts;
     constructor(options) {
@@ -63,7 +76,7 @@ export class Agent {
             syncGroups: options.syncGroups,
             fetch: options.fetch ?? globalThis.fetch.bind(globalThis),
             timeoutMs: options.timeoutMs ?? 5_000,
-            logger: options.logger ?? consoleLogger,
+            logger: options.logger ?? defaultAgentLogger(),
         };
     }
     /**
@@ -72,11 +85,10 @@ export class Agent {
      * tokens before TTL elapses. Use on the server when the same agent
      * identity handles many requests.
      *
-     * Returns the cache, NOT an `Agent` instance: the long-lived path
-     * uses `Ablo({kind:'agent'})` over WebSocket, while the `Agent` class
-     * itself is the short-lived REST helper for AI SDK tool loops. The
-     * static method lives here so consumers reach for everything
-     * agent-related under one namespace.
+     * Returns the cache rather than an `Agent` instance: the long-lived path
+     * uses `Ablo({kind:'agent'})` over a WebSocket, while the `Agent` class
+     * itself is the short-lived REST helper for AI SDK tool loops. The static
+     * method lives here so everything agent-related sits under one namespace.
      *
      * ```ts
      * const session = Agent.session({ syncServerUrl, schema, issueToken });
@@ -90,8 +102,8 @@ export class Agent {
     }
     /**
      * Extract the Agent instance from an AI SDK tool's
-     * `experimental_context`. Use inside tool `execute` functions to reach
-     * the perception without closure-capturing it.
+     * `experimental_context`. Use it inside a tool's `execute` function to
+     * reach the agent without capturing it in a closure.
      *
      * ```ts
      * execute: async (args, { experimental_context }) => {
@@ -117,9 +129,9 @@ export class Agent {
         return ctx.perception;
     }
     /**
-     * Narrower variant of {@link fromContext} that returns `undefined` instead
-     * of throwing when perception isn't in context. Useful for tools where
-     * awareness is optional (e.g., read-only tools that work without it).
+     * A lenient variant of {@link fromContext} that returns `undefined` instead
+     * of throwing when no agent is present in the context. Useful for tools
+     * where awareness is optional, such as read-only tools that work without it.
      */
     static tryFromContext(ctx) {
         if (!ctx ||
@@ -222,9 +234,10 @@ export class Agent {
                     pendingClaims,
                 };
             }
-            const body = (await res.json());
+            const body = (await (res).json());
             const rows = body.results?.[0];
-            if (!rows || rows.length === 0) {
+            const entity = rows?.[0];
+            if (!entity) {
                 return {
                     stale: true,
                     reason: 'not_found',
@@ -232,7 +245,6 @@ export class Agent {
                     pendingClaims,
                 };
             }
-            const entity = rows[0];
             const updatedAtRaw = entity.updated_at ?? entity.updatedAt;
             const lastModifiedBy = entity.updated_by ??
                 entity.updatedBy ??

package/dist/agent/index.d.ts

@@ -4,7 +4,7 @@
  * Two entry points depending on agent lifetime:
  *
  * ─────────────────────────────────────────────────────────────────────────
- * LONG-LIVED AGENT (browser, daemon, persistent Node process)
+ * Long-lived agents (browser, daemon, persistent Node process)
  * ─────────────────────────────────────────────────────────────────────────
  * Use the unified `Ablo({...})` factory directly with `kind: 'agent'`.
  * The factory holds the WebSocket, reactive subscriptions, mutations, and
@@ -36,7 +36,7 @@
  * before expiry.
  *
  * ─────────────────────────────────────────────────────────────────────────
- * SHORT-LIVED AGENT (SQS consumer, serverless, API route)
+ * Short-lived agents (queue consumer, serverless, API route)
  * ─────────────────────────────────────────────────────────────────────────
  * Use {@link Agent}. Stateless REST hooks that slot directly into
  * the Vercel AI SDK's `generateText` / `streamText`. No WebSocket. Ideal
@@ -69,7 +69,7 @@
  * ```
  *
  * ─────────────────────────────────────────────────────────────────────────
- * IDIOMATIC TOOL PATTERN (ported from vercel-labs/open-agents)
+ * Idiomatic tool pattern
  * ─────────────────────────────────────────────────────────────────────────
  * Tools are factory functions that pull ambient state from
  * `experimental_context`. The caller builds an {@link AgentContext} once
@@ -93,7 +93,7 @@
  * ```
  *
  * ─────────────────────────────────────────────────────────────────────────
- * COMPOSED (long-lived `Ablo({kind:'agent'})` + Agent together)
+ * Composed usage (a long-lived `Ablo({kind:'agent'})` plus an Agent)
  * ─────────────────────────────────────────────────────────────────────────
  * If you have a long-lived `Ablo` instance AND want AI SDK hooks, pass it
  * as the `announcer` to Agent — presence announcements route

package/dist/agent/index.js

@@ -4,7 +4,7 @@
  * Two entry points depending on agent lifetime:
  *
  * ─────────────────────────────────────────────────────────────────────────
- * LONG-LIVED AGENT (browser, daemon, persistent Node process)
+ * Long-lived agents (browser, daemon, persistent Node process)
  * ─────────────────────────────────────────────────────────────────────────
  * Use the unified `Ablo({...})` factory directly with `kind: 'agent'`.
  * The factory holds the WebSocket, reactive subscriptions, mutations, and
@@ -36,7 +36,7 @@
  * before expiry.
  *
  * ─────────────────────────────────────────────────────────────────────────
- * SHORT-LIVED AGENT (SQS consumer, serverless, API route)
+ * Short-lived agents (queue consumer, serverless, API route)
  * ─────────────────────────────────────────────────────────────────────────
  * Use {@link Agent}. Stateless REST hooks that slot directly into
  * the Vercel AI SDK's `generateText` / `streamText`. No WebSocket. Ideal
@@ -69,7 +69,7 @@
  * ```
  *
  * ─────────────────────────────────────────────────────────────────────────
- * IDIOMATIC TOOL PATTERN (ported from vercel-labs/open-agents)
+ * Idiomatic tool pattern
  * ─────────────────────────────────────────────────────────────────────────
  * Tools are factory functions that pull ambient state from
  * `experimental_context`. The caller builds an {@link AgentContext} once
@@ -93,7 +93,7 @@
  * ```
  *
  * ─────────────────────────────────────────────────────────────────────────
- * COMPOSED (long-lived `Ablo({kind:'agent'})` + Agent together)
+ * Composed usage (a long-lived `Ablo({kind:'agent'})` plus an Agent)
  * ─────────────────────────────────────────────────────────────────────────
  * If you have a long-lived `Ablo` instance AND want AI SDK hooks, pass it
  * as the `announcer` to Agent — presence announcements route
@@ -114,7 +114,7 @@
  */
 // ── The entire `/agent` surface — one symbol ────────────────────────────
 //
-// `Agent` is the class AND the namespace for its types. Reach for
+// `Agent` is both the class and the namespace for its types. Reach for
 // options, context, and session options via dot access:
 //
 //   import { Agent } from '@abloatai/ablo/agent';

package/dist/agent/session.d.ts

@@ -1,23 +1,21 @@
 /**
- * Agent session — cache + lifecycle for server-side `SyncAgent`s.
+ * Caches and manages the lifecycle of long-lived agent connections on a server.
  *
- * Captures the pattern every server-side consumer needs:
- *   1. Cache `SyncAgent` instances per (org, user, surface, target).
- *   2. Re-mint capabilities before TTL elapses.
- *   3. Align the SyncAgent ctor's `syncGroups` with the cap allowlist
- *      so the upgrade-time intersection is non-empty (avoid the
- *      silent black-hole-broadcast bug).
- *   4. Connect / disconnect / dispose lifecycle.
+ * Server code that runs AI agents typically needs the same four things, and this
+ * module handles all of them:
+ *   1. Reuse one connected agent per (organization, user, surface, target)
+ *      instead of connecting anew on every request.
+ *   2. Re-issue the agent's capability token before it expires.
+ *   3. Request exactly the sync groups the token allows, so the two lists
+ *      overlap. If they don't, the agent subscribes to nothing and every
+ *      broadcast is silently filtered out.
+ *   4. Connect, disconnect, and dispose cleanly.
  *
- * What's generic, what isn't:
- *   - Cache, TTL, sync_groups alignment, lifecycle: SAME for every
- *     consumer. Lives here.
- *   - Cap mint: AUTH-FLOW-SPECIFIC. Every consumer has a different
- *     way to obtain a token (Better Auth cookie forwarding, API key
- *     exchange, OAuth, etc.). Consumer provides via the
- *     `issueToken` callback.
- *
- * The helper itself imports nothing app-specific. Open-source-clean.
+ * Everything except obtaining the token is the same for every caller and lives
+ * here. Obtaining the token depends on how you authenticate — cookie forwarding,
+ * API-key exchange, OAuth, and so on — so you supply that step through the
+ * {@link AgentSessionOptions.issueToken} callback. The module itself depends on
+ * nothing outside this package.
  */
 import { Ablo } from '../client/Ablo.js';
 import type { Schema, SchemaRecord } from '../schema/schema.js';
@@ -25,11 +23,11 @@ interface IssuedToken {
     readonly token: string;
     readonly expiresAtMs: number;
     /**
-     * Sync groups allowed by this capability. Must include every group
-     * the agent will subscribe to — the upgrade-time intersection of
-     * (allowed) ∩ (requested) determines effective subscription. Returning
-     * a list that doesn't include the needed groups produces an empty
-     * intersection and silent broadcast failure.
+     * The sync groups this token grants access to. It must include every group the
+     * agent needs to subscribe to. The agent's effective subscription is the
+     * overlap between the groups it requests and the groups listed here, so a list
+     * that omits a needed group leaves the agent subscribed to nothing and silently
+     * receiving no broadcasts.
      */
     readonly syncGroups: readonly string[];
 }
@@ -37,8 +35,9 @@ interface AgentIdentity {
     readonly userId: string;
     readonly organizationId: string;
     /**
-     * Surface class — `'chat'`, `'mcp'`, `'agent_worker'`, etc. Session
-     * caches per surface so two surfaces don't share token or WS.
+     * The kind of surface making the request, such as `'chat'`, `'mcp'`, or
+     * `'agent_worker'`. The cache keys on this value, so two surfaces never share a
+     * token or a WebSocket connection.
      */
     readonly surfaceClass: string;
     readonly target?: {
@@ -47,40 +46,44 @@ interface AgentIdentity {
     } | null;
 }
 export interface AgentSessionOptions<R extends SchemaRecord = SchemaRecord> {
-    /** Sync-server WebSocket URL — `wss://sync.example.com` or `ws://localhost:3001`. */
+    /** WebSocket URL of your sync server, such as `wss://sync.example.com` or `ws://localhost:3001`. */
     readonly syncServerUrl: string;
-    /** Schema for the typed model proxy on the returned Ablo. After
-     *  the dual-engine collapse, `Ablo({kind:'agent'})` is the unified
-     *  factory and requires the schema to expose
-     *  `agent.<model>.create/update/delete`. */
+    /**
+     * Your schema, used to build the typed model proxy on the returned client. The
+     * agent client exposes it as `agent.<model>.create/update/delete`.
+     */
     readonly schema: Schema<R>;
     /**
-     * Token-issuing callback. Called on cache miss / expiry. Owns the
-     * consumer's auth flow (Better Auth cookies, API key exchange, OAuth,
-     * etc.) so the engine stays auth-flow-agnostic.
+     * Issues a capability token for the given identity. The session calls it on a
+     * cache miss or when the current token is near expiry. Because this callback
+     * carries out your authentication flow — cookie forwarding, API-key exchange,
+     * OAuth, and so on — the rest of the session stays independent of how you
+     * authenticate.
      */
     readonly issueToken: (identity: AgentIdentity) => Promise<IssuedToken>;
     /**
-     * Soft window before actual expiry to re-mint. Defaults to 30s.
-     * Avoids races between mint-time and clock-skew at use-time.
+     * How long before a token's true expiry the session should re-issue it, in
+     * milliseconds. Defaults to 30 seconds. The buffer absorbs clock skew so a
+     * token never expires mid-use.
      */
     readonly reissueBufferMs?: number;
     /**
-     * Optional agent-id strategy. Default: `${surfaceClass}:${userId}`.
-     * Override when the consumer wants different attribution shape.
+     * How to derive the agent's identifier from the request identity. Defaults to
+     * `${surfaceClass}:${userId}`. Override it when you want a different shape for
+     * attribution.
      */
     readonly agentIdFor?: (identity: AgentIdentity) => string;
 }
 /**
- * Returns a session whose `getAgent` method handles cache, mint,
- * sync_groups alignment, and lifecycle. Call `disposeAll()` from
- * the consumer's process shutdown hook.
+ * Creates a session that hands out connected agents on demand. Its `getAgent`
+ * method handles caching, token issuance, sync-group alignment, and connection
+ * lifecycle; call `disposeAll` from your process's shutdown hook to close every
+ * open connection.
  *
- * Threading: the session is intended to be a long-lived singleton
- * shared across requests. The cache is keyed precisely so two
- * concurrent requests for the same (user, org, surface, target)
- * share one agent + one WS, while different requests get
- * independent agents.
+ * Treat the session as a long-lived singleton shared across requests. The cache
+ * key combines organization, user, surface, and target, so two concurrent
+ * requests for the same combination share one agent and one WebSocket, while
+ * requests for different combinations get independent agents.
  */
 export declare function createAgentSession<R extends SchemaRecord = SchemaRecord>(options: AgentSessionOptions<R>): {
     getAgent: (identity: AgentIdentity) => Promise<Ablo<R>>;