@abloatai/ablo 0.26.0 → 0.27.0

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[];
 }
@@ -231,16 +227,16 @@ export interface WrapToolOptions<TArgs> {
     announceOnExecute?: boolean;
 }
 /**
- * Console-backed default logger — the SAME gated factory the `Ablo()` client
- * uses (`createConsoleLogger`, threshold from `ABLO_LOG_LEVEL`, default
- * `warn`), tagged `[agent]` so agent-runtime lines are distinguishable. The
- * previous hand-rolled shim ignored the level gate entirely and printed
- * `[perception]` engine internals at debug/info by default. Level is resolved
- * per construction (not at module load) so `ABLO_LOG_LEVEL` set by the host
- * process before building an Agent is honored.
+ * 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 for the unit test that pins the gating; consumers pass their own
- * `logger` option instead.
+ * 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 {
@@ -252,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 });
@@ -268,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 }) => {
@@ -285,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

@@ -44,16 +44,16 @@ import { createConsoleLogger, resolveLogLevel } from '../client/consoleLogger.js
 import { AbloValidationError } from '../errors.js';
 // ── Agent ───────────────────────────────────────────────────────
 /**
- * Console-backed default logger — the SAME gated factory the `Ablo()` client
- * uses (`createConsoleLogger`, threshold from `ABLO_LOG_LEVEL`, default
- * `warn`), tagged `[agent]` so agent-runtime lines are distinguishable. The
- * previous hand-rolled shim ignored the level gate entirely and printed
- * `[perception]` engine internals at debug/info by default. Level is resolved
- * per construction (not at module load) so `ABLO_LOG_LEVEL` set by the host
- * process before building an Agent is honored.
+ * 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 for the unit test that pins the gating; consumers pass their own
- * `logger` option instead.
+ * 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());
@@ -85,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 });
@@ -103,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 }) => {
@@ -130,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 ||

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>>;

package/dist/agent/session.js

@@ -1,37 +1,35 @@
 /**
- * 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 { AbloConnectionError } from '../errors.js';
 import { getContext } from '../context.js';
 /**
- * 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 function createAgentSession(options) {
     const reissueBufferMs = options.reissueBufferMs ?? 30_000;
@@ -61,21 +59,14 @@ export function createAgentSession(options) {
             }
         }
         const minted = await options.issueToken(identity);
-        // Sync_groups alignment is the load-bearing detail. The SDK
-        // ctor's `syncGroups` and the cap mint's `syncGroups`
-        // MUST overlap or the upgrade intersection is empty and every
-        // broadcast filter returns false. Use the cap's allowed list
-        // verbatim — the caller controlled what went in there, so it's
-        // exactly what the SDK should request.
-        // `AbloOptions` exposes the URL as `baseURL` (resolved by
-        // `resolveBaseURL`). Earlier code passed `url:` here — `Ablo()`
-        // silently dropped the unknown field (the cast below masked the
-        // type error) and `resolveBaseURL` fell through to the hosted
-        // default `wss://api.abloatai.com`. Staging surfaced the bug
-        // 2026-05-07 — DNS lookup hit the wrong
-        // host even though the caller threaded `syncServerUrl` through
-        // correctly. Forward as `baseURL` so the caller's URL is the only
-        // source of truth and the package default never silently applies.
+        // Request the same sync groups the token grants. The groups requested here
+        // and the groups the token allows must overlap; otherwise their intersection
+        // is empty and every broadcast is filtered out. The token's allowed list is
+        // exactly what to request, since the caller decided what went into it.
+        //
+        // Pass the URL as `baseURL`, the field the client reads. Any other field name
+        // is ignored, in which case the client would fall back to its default host,
+        // so `baseURL` keeps the caller's URL the single source of truth.
         const wsUrl = toWsUrl(options.syncServerUrl);
         const agentOptions = {
             baseURL: wsUrl,
@@ -101,11 +92,9 @@ export function createAgentSession(options) {
                 await agent.dispose();
             }
             catch { /* ignore */ }
-            // Route through the gated logger so this obeys ABLO_LOG_LEVEL like every
-            // other line: a plain consumer-register `error` headline (the unreachable
-            // URL + code), with the structured fields on a `debug` companion. The
-            // companion's shape matches the cap-mint logger in `connectAgent.ts` so a
-            // single search picks both up.
+            // Log through the level-gated logger so it honors ABLO_LOG_LEVEL: an
+            // `error` headline naming the unreachable URL and code, plus a `debug`
+            // companion carrying the structured fields for deeper diagnosis.
             const log = getContext().logger;
             log.error(`Agent could not connect to the sync server at ${wsUrl}${code ? ` (${code})` : ''}.`);
             log.debug('[Agent.session] ws bootstrap failed', {
@@ -135,9 +124,9 @@ export function createAgentSession(options) {
         cacheByKey.clear();
     }
     /**
-     * Eject a specific cached agent — useful when the consumer knows
-     * the underlying token is invalidated (revocation, role change)
-     * and wants the next `getAgent` call to mint fresh.
+     * Removes and disposes one cached agent. Call it when you know the agent's
+     * token is no longer valid — after a revocation or role change, for example —
+     * so the next `getAgent` call issues a fresh one.
      */
     function evict(identity) {
         const key = cacheKey(identity);