@abloatai/ablo 0.25.0 → 0.27.0

package/dist/ai-sdk/index.d.ts

@@ -72,22 +72,24 @@
  * to one entity before any tool is chosen; tool implementations stay exactly
  * the same.
  *
- * ## Multi-agent coordination — the canonical way
- *
- * When several agents (or agents + humans) write the SAME row concurrently, the
- * outcome is decided by **(write path) × (the model's conflict policy)**, NOT by
- * how smart the model is. The same model silently loses 3 of 4 concurrent
- * contributions through a blind whole-row write, and lands all 4 through a
- * coordinated one — because the coordinated write returns a *signal* the model
- * (or the runtime) acts on. Two empirical laws fall out:
- *
- *   1. **Surface the signal.** A write that swallows the conflict and reports
- *      success is the footgun. Every robust path returns a legible result
- *      (`reject` → re-read & retry; `claimed` → the model tries again) instead of
- *      clobbering. Reaching for a bigger model does not fix a silent write.
- *   2. **Back off.** Under N-way contention, writers that retry in lock-step just
- *      re-collide. The shared reconcile loop already jitters its backoff; any
- *      hand-rolled retry must too, or it exhausts its budget and drops a writer.
+ * ## Multi-agent coordination
+ *
+ * When several agents, or agents and people, write the same row at once, the
+ * outcome depends on the write path and the model's conflict policy, not on how
+ * capable the model is. The same model silently loses three of four concurrent
+ * contributions through a blind whole-row write, yet lands all four through a
+ * coordinated one, because a coordinated write returns a signal the model or the
+ * runtime can act on. Two rules follow:
+ *
+ *   1. Surface the signal. A write that swallows the conflict and reports success
+ *      is the trap. Every reliable path returns a legible result instead of
+ *      overwriting — a rejection leads to a re-read and retry, and a `'claimed'`
+ *      result leads the model to try again. A larger model does not fix a silent
+ *      write.
+ *   2. Back off. Under heavy contention, writers that retry in lock-step simply
+ *      collide again. The shared reconcile loop already jitters its backoff, and
+ *      any retry you write by hand should too, or it exhausts its budget and drops
+ *      a writer.
  *
  * `coordinatedTool` (below) encodes both. Prefer it over a hand-written tool for
  * "save the agent's contribution into the shared row":
@@ -107,12 +109,13 @@
  * |----------|-------------------|---------------|------------------------|
  * | `merge`  | accumulate (CAS)  | re-read + re-apply (silent, backed off) | must be `reject` (default) |
  * | `claim`  | mutual exclusion  | returns `{status:'claimed'}` → model retries | any |
- * | `queue`  | FIFO-ish (SQS)    | poll-acquire until granted / timeout | any |
+ * | `queue`  | FIFO-ish (poll)   | poll-acquire until granted / timeout | any |
  *
- * Note: a model declaring `agentsNotify()` HOLDS a losing write instead of
- * rejecting it, which defeats `merge`'s reconcile (the loser is dropped, not
- * retried). Use `agentsReject()` for accumulate semantics, or `claim`/`queue`.
+ * Note: a model that declares `agentsNotify()` holds a losing write rather than
+ * rejecting it, which defeats `'merge'`'s reconcile loop — the loser is dropped
+ * instead of retried. Use `agentsReject()` for accumulate semantics, or the
+ * `'claim'` or `'queue'` strategy.
  */
-export { coordinationContextMiddleware, type CoordinationContextMiddlewareOptions, type ClaimTarget, } from './coordination-context.js';
+export { coordinationContextMiddleware, type CoordinationContextMiddlewareOptions, type ClaimTarget, } from './coordinationContext.js';
 export { wrapWithMultiplayer, type WrapWithMultiplayerOptions } from './wrap.js';
-export { coordinatedTool, type CoordinationStrategy, type CoordinatedToolOptions, type CoordinatedWriteResult, } from './coordinated-tool.js';
+export { coordinatedTool, type CoordinationStrategy, type CoordinatedToolOptions, type CoordinatedWriteResult, } from './coordinatedTool.js';

package/dist/ai-sdk/index.js

@@ -72,22 +72,24 @@
  * to one entity before any tool is chosen; tool implementations stay exactly
  * the same.
  *
- * ## Multi-agent coordination — the canonical way
- *
- * When several agents (or agents + humans) write the SAME row concurrently, the
- * outcome is decided by **(write path) × (the model's conflict policy)**, NOT by
- * how smart the model is. The same model silently loses 3 of 4 concurrent
- * contributions through a blind whole-row write, and lands all 4 through a
- * coordinated one — because the coordinated write returns a *signal* the model
- * (or the runtime) acts on. Two empirical laws fall out:
- *
- *   1. **Surface the signal.** A write that swallows the conflict and reports
- *      success is the footgun. Every robust path returns a legible result
- *      (`reject` → re-read & retry; `claimed` → the model tries again) instead of
- *      clobbering. Reaching for a bigger model does not fix a silent write.
- *   2. **Back off.** Under N-way contention, writers that retry in lock-step just
- *      re-collide. The shared reconcile loop already jitters its backoff; any
- *      hand-rolled retry must too, or it exhausts its budget and drops a writer.
+ * ## Multi-agent coordination
+ *
+ * When several agents, or agents and people, write the same row at once, the
+ * outcome depends on the write path and the model's conflict policy, not on how
+ * capable the model is. The same model silently loses three of four concurrent
+ * contributions through a blind whole-row write, yet lands all four through a
+ * coordinated one, because a coordinated write returns a signal the model or the
+ * runtime can act on. Two rules follow:
+ *
+ *   1. Surface the signal. A write that swallows the conflict and reports success
+ *      is the trap. Every reliable path returns a legible result instead of
+ *      overwriting — a rejection leads to a re-read and retry, and a `'claimed'`
+ *      result leads the model to try again. A larger model does not fix a silent
+ *      write.
+ *   2. Back off. Under heavy contention, writers that retry in lock-step simply
+ *      collide again. The shared reconcile loop already jitters its backoff, and
+ *      any retry you write by hand should too, or it exhausts its budget and drops
+ *      a writer.
  *
  * `coordinatedTool` (below) encodes both. Prefer it over a hand-written tool for
  * "save the agent's contribution into the shared row":
@@ -107,12 +109,13 @@
  * |----------|-------------------|---------------|------------------------|
  * | `merge`  | accumulate (CAS)  | re-read + re-apply (silent, backed off) | must be `reject` (default) |
  * | `claim`  | mutual exclusion  | returns `{status:'claimed'}` → model retries | any |
- * | `queue`  | FIFO-ish (SQS)    | poll-acquire until granted / timeout | any |
+ * | `queue`  | FIFO-ish (poll)   | poll-acquire until granted / timeout | any |
  *
- * Note: a model declaring `agentsNotify()` HOLDS a losing write instead of
- * rejecting it, which defeats `merge`'s reconcile (the loser is dropped, not
- * retried). Use `agentsReject()` for accumulate semantics, or `claim`/`queue`.
+ * Note: a model that declares `agentsNotify()` holds a losing write rather than
+ * rejecting it, which defeats `'merge'`'s reconcile loop — the loser is dropped
+ * instead of retried. Use `agentsReject()` for accumulate semantics, or the
+ * `'claim'` or `'queue'` strategy.
  */
-export { coordinationContextMiddleware, } from './coordination-context.js';
+export { coordinationContextMiddleware, } from './coordinationContext.js';
 export { wrapWithMultiplayer } from './wrap.js';
-export { coordinatedTool, } from './coordinated-tool.js';
+export { coordinatedTool, } from './coordinatedTool.js';

package/dist/ai-sdk/wrap.d.ts

@@ -13,7 +13,7 @@
  * const wrapped = wrapWithMultiplayer({
  *   model: anthropic('claude-opus-4-7'),
  *   agent,
- *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
+ *   target: { type: 'SlideDeck', id: 'deck-abc' },
  * });
  *
  * const result = streamText({
@@ -29,7 +29,7 @@ import { wrapLanguageModel } from 'ai';
 import type { LanguageModelV3, LanguageModelV3Middleware } from '@ai-sdk/provider';
 import type { Ablo } from '../client/Ablo.js';
 import type { SchemaRecord } from '../schema/schema.js';
-import { type ClaimTarget } from './coordination-context.js';
+import { type ClaimTarget } from './coordinationContext.js';
 export interface WrapWithMultiplayerOptions<R extends SchemaRecord = SchemaRecord> {
     /** The base language model to wrap. Consumer brings their own. */
     readonly model: LanguageModelV3;
@@ -52,14 +52,13 @@ export interface WrapWithMultiplayerOptions<R extends SchemaRecord = SchemaRecor
      */
     readonly excludeClaimIds?: readonly string[];
     /**
-     * Optional extra middleware to compose. Runs in the order given,
-     * INSIDE the multiplayer middlewares (so the multiplayer wrap is
-     * the outer-most). Useful for caching, observability, custom
-     * transforms that should not affect the multiplayer signal.
+     * Extra middleware to compose. It runs in the order given, nested inside the
+     * multiplayer middleware, so the multiplayer wrap stays the outermost layer.
+     * Use it for caching, observability, or custom transforms that should not
+     * affect the multiplayer signal.
      *
      * For full control over ordering, skip this helper and call
-     * `wrapLanguageModel` directly with all middleware in the order
-     * you want.
+     * `wrapLanguageModel` directly with all the middleware in the order you want.
      */
     readonly extraMiddleware?: readonly LanguageModelV3Middleware[];
 }

package/dist/ai-sdk/wrap.js

@@ -13,7 +13,7 @@
  * const wrapped = wrapWithMultiplayer({
  *   model: anthropic('claude-opus-4-7'),
  *   agent,
- *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
+ *   target: { type: 'SlideDeck', id: 'deck-abc' },
  * });
  *
  * const result = streamText({
@@ -26,7 +26,7 @@
  * ```
  */
 import { wrapLanguageModel } from 'ai';
-import { coordinationContextMiddleware, } from './coordination-context.js';
+import { coordinationContextMiddleware, } from './coordinationContext.js';
 export function wrapWithMultiplayer(options) {
     const { model, agent, target, excludeClaimIds, extraMiddleware } = options;
     return wrapLanguageModel({

package/dist/auth/credentialPolicy.d.ts

@@ -1,66 +1,65 @@
 /**
- * Credential POLICY — the single source of truth for "what KIND of credential
- * did the caller hand us, and what do we DO with it at connect time".
+ * Decides what a credential is and how to use it when a client connects. A
+ * caller configures an Ablo client with an API key, and this module answers two
+ * questions about that value: which of the four key kinds it is, and which
+ * connect-time route it takes.
  *
- * Before this module the prefix-dispatch decision (`sk_`/`ek_`/`rk_`/`pk_`) was
- * re-implemented with raw `startsWith()` sniffs in ~5 places (identity.ts ×3,
- * auth.ts browser guard, cli/dev.ts, cli/push.ts) and the connect-time routing
- * lived as a 4-branch if/elif tree inside `resolveParticipantIdentity`. Folding
- * the policy here keeps the kind-taxonomy and the connect decision in ONE place;
- * the consumers below just call into it.
+ * The routing decision is the only thing that lives here. This module does not
+ * perform the network calls that mint or exchange credentials;
+ * {@link resolveCredential} delegates those to primitives the caller supplies,
+ * so the decision of what to do stays separate from the work of doing it.
  *
- * This module is deliberately POLICY-ONLY. It does NOT own the auth primitives
- * (`exchangeApiKey` / `mintUserSessionKey` / `resolveIdentity`), the credential
- * lifecycle (`startCredentialLifecycle` / refresh scheduler), or the connection
- * FSM — those are correctly distributed consumers. `resolveCredential` DELEGATES
- * to injected primitives rather than reimplementing any HTTP mint call.
- *
- * Browser-safe: `classifyCredentialKind` is a pure-string helper and MUST NOT
- * import the Node-only `keys` module (`node:crypto`). The key-prefix contract it
- * encodes mirrors `keys/index.ts`'s `KIND_BY_PREFIX` (the Stripe-style model:
- * sk_=secret, rk_=restricted, ek_=ephemeral, pk_=publishable) but stays a plain
- * prefix lookup so it can ship in the client bundle.
+ * {@link classifyCredentialKind} is a plain string check with no Node
+ * dependencies, so it is safe to run in a browser bundle. It recognizes the key
+ * prefixes `sk_` (secret), `rk_` (restricted), `ek_` (ephemeral), and `pk_`
+ * (publishable), but does not validate a key's checksum or environment segment.
  */
 import type { exchangeApiKey, mintUserSessionKey, resolveIdentity } from './index.js';
-import type { resolveApiKeyValue } from '../client/auth.js';
 /**
- * The four Ablo API-key kinds (Stripe-style). Prefix contract — kept in lockstep
- * with `keys/index.ts` `API_KEY_KINDS` / `KIND_BY_PREFIX`, but declared locally
- * so this browser-safe module never pulls in `node:crypto`.
+ * The shape of the function that resolves a configured `apiKey` — which may be a
+ * string or an async setter — down to a concrete string, or `null` when no key
+ * is available. It is declared here structurally, rather than imported, to avoid
+ * a circular dependency between this module and the code that supplies the
+ * function. Any function with a matching shape satisfies it.
+ */
+type ResolveApiKeyValueFn = (apiKey: string | (() => Promise<string | null>) | null) => Promise<string | null>;
+/**
+ * The four kinds of Ablo API key, one per prefix: `sk_` is secret, `ek_` is
+ * ephemeral, `rk_` is restricted, and `pk_` is publishable. The list is declared
+ * here, rather than imported, so this browser-safe module stays free of Node-only
+ * dependencies.
  */
 export type CredentialKind = 'secret' | 'ephemeral' | 'restricted' | 'publishable';
 /**
- * Lightweight, browser-safe prefix → kind classifier. The SINGLE source of truth
- * for prefix dispatch across the SDK (connect routing, the browser guard, the
- * CLI key-gating). Returns `null` for a value that carries no recognized Ablo
- * key prefix (a caller-supplied capability/auth token, an empty/garbage value).
- *
- * Pure string check — does NOT validate the checksum or environment segment
- * (that's `keys/index.ts` `parseApiKey`, which is Node-only). This is only the
- * "which of the four buckets" decision.
+ * Classifies a credential by its prefix, returning its {@link CredentialKind}, or
+ * `null` when the value carries no recognized Ablo key prefix — for example a
+ * capability or auth token the caller supplied, or an empty string. This is a
+ * plain string check that is safe to run in a browser; it decides only which of
+ * the four kinds a value is, and does not validate the key's checksum or
+ * environment segment.
  */
 export declare function classifyCredentialKind(value: string): CredentialKind | null;
 /**
- * Auth primitives injected into {@link resolveCredential}. Each is the canonical
- * implementation from `auth/index.ts` / `client/auth.ts`; the policy DELEGATES to
- * them so the HTTP mint logic stays in ONE place and only the routing decision
- * lives here. `mintUserSessionKey` is carried for completeness of the primitive
- * surface (the browser/session path mints it before connect); `resolveCredential`
- * never re-mints it — a pre-minted `ek_` arrives ready to use.
+ * The set of authentication primitives that {@link resolveCredential} delegates
+ * to. Injecting them keeps the network calls that mint and exchange credentials
+ * in one place and leaves this module responsible only for the routing decision.
+ * {@link resolveCredential} never calls `mintUserSessionKey` itself — an
+ * ephemeral `ek_` key is minted before the client connects and arrives ready to
+ * use — but it is listed here to describe the full primitive surface.
  */
 export interface CredentialPrimitives {
     readonly exchangeApiKey: typeof exchangeApiKey;
     readonly mintUserSessionKey: typeof mintUserSessionKey;
     readonly resolveIdentity: typeof resolveIdentity;
-    readonly resolveApiKeyValue: typeof resolveApiKeyValue;
+    readonly resolveApiKeyValue: ResolveApiKeyValueFn;
 }
 export interface ResolveCredentialContext {
     readonly primitives: CredentialPrimitives;
     /**
-     * Build the argument bag for the hosted exchange. identity.ts owns the baseUrl
-     * derivation + participant scope, so it supplies the args; the policy invokes
-     * `primitives.exchangeApiKey` with them. The `apiKey` is filled in by the policy
-     * from the resolved value.
+     * The arguments for the credential exchange, minus the `apiKey`. The caller
+     * derives the base URL and participant scope and supplies them here;
+     * {@link resolveCredential} fills in the resolved `apiKey` and calls
+     * `exchangeApiKey`.
      */
     readonly exchangeArgs: Omit<Parameters<typeof exchangeApiKey>[0], 'apiKey'>;
 }
@@ -73,23 +72,23 @@ export interface ResolveCredentialInput {
     readonly capabilityToken: string | undefined;
     /** Configured static `authToken`. */
     readonly authToken: string | null;
-    /** True once the caller knows its own identity (legacy explicit path). */
+    /** True when the caller already knows its own identity, so no server round-trip is needed to resolve it. */
     readonly hasExplicitIdentity: boolean;
 }
 /**
- * The connect-time decision, expressed as a discriminated union over the routing
- * kind (NOT the raw key kind — `ek_` and `rk_` collapse into the same
- * `pre-minted` route, and a bare capability token routes the same way). The
- * caller (`identity.ts`) switches on `kind` and performs the scope/side-effect
- * wiring each route needs.
+ * The outcome of the connect-time decision, as a discriminated union over the
+ * route rather than the key kind: an `ek_` and an `rk_` key both take the
+ * `pre-minted` route, as does a bare capability token. The caller switches on
+ * `kind` and wires up the scope and side effects each route needs.
  *
- * Fields carry exactly what each branch in the old if/elif tree produced:
- *   - `getBearer`        — the token to authenticate the bootstrap/`/auth/*` HTTP
- *                          and to seed the credential source with.
- *   - `expiresAtMs`      — exchange expiry (drives the refresh scheduler) or null
- *                          when the credential never expires / nothing to refresh.
- *   - `controlPlaneKey`  — the ORIGINAL configured apiKey when the route minted
- *                          via exchange (so a refresh can re-mint), else null.
+ * Every variant carries the same three fields:
+ *   - `getBearer` — the token used to authenticate the bootstrap and `/auth/*`
+ *     requests, and to seed the credential source.
+ *   - `expiresAtMs` — when the credential expires, which drives the refresh
+ *     scheduler, or `null` when there is nothing to refresh.
+ *   - `controlPlaneKey` — the original configured API key when the route minted
+ *     its bearer through an exchange, so a refresh can mint again; otherwise
+ *     `null`.
  */
 export type ResolvedCredential = 
 /** `pk_` — long-lived browser-safe read-only project key. Used directly as the
@@ -111,16 +110,16 @@ export type ResolvedCredential =
     /** The configured apiKey (string or setter) — read fresh on each refresh. */
     readonly controlPlaneKey: string | (() => Promise<string | null>);
 }
-/** Pre-minted `ek_`/`rk_` OR an explicit capability/auth token — used AS-IS as
- *  the bearer (never exchanged). Identity resolved via `/auth/identity`. */
+/** A pre-minted `ek_` or `rk_` key, or an explicit capability or auth token,
+ *  used as the bearer without any exchange. Identity resolved via `/auth/identity`. */
  | {
     readonly kind: 'pre-minted';
     readonly getBearer: string;
     readonly expiresAtMs: null;
     readonly controlPlaneKey: null;
 }
-/** Legacy explicit — caller knows its own organizationId + user/agentId. No
- *  server round-trip; the (optional) bearer is the initial cap token. */
+/** The caller already knows its own organization and user or agent id, so there
+ *  is no server round-trip; the optional bearer is the initial capability token. */
  | {
     readonly kind: 'explicit';
     readonly getBearer: string | undefined;
@@ -128,18 +127,22 @@ export type ResolvedCredential =
     readonly controlPlaneKey: null;
 };
 /**
- * Connect-time credential routing — absorbs the decision tree that used to live
- * inline in `resolveParticipantIdentity`. Classifies the configured apiKey, then
- * routes to one of four outcomes, DELEGATING the actual HTTP exchange to the
- * injected `exchangeApiKey` primitive. The caller switches on
- * `ResolvedCredential.kind` to perform scope wiring + scheduler setup.
+ * Routes a configured API key to its connect-time outcome. It classifies the
+ * key, then returns one of four {@link ResolvedCredential} variants, delegating
+ * any credential exchange to the injected `exchangeApiKey` primitive. The caller
+ * switches on the result's `kind` to wire up scope and the refresh scheduler.
  *
- * Routing (preserves the old branch order exactly):
- *   0. `pk_` + no explicit cap token → `publishable` (direct bearer, no refresh).
- *   1. exchangeable apiKey (any prefix that ISN'T a pre-minted `ek_`/`rk_`) +
- *      no explicit cap token → `exchange` (hosted-cloud round-trip + scheduler).
- *   2. otherwise, identity unknown → `pre-minted` (use the cap token as-is). Throws
- *      `session_expired` when there is no token to authenticate `/auth/identity`.
- *   3. otherwise (identity known) → `explicit` (legacy self-hosted, no round-trip).
+ * The routes, in the order they are tried:
+ *   0. A `pk_` key with no explicit capability token becomes `publishable`: used
+ *      directly as the bearer, with no refresh.
+ *   1. Any other exchangeable key (one that is not a pre-minted `ek_` or `rk_`)
+ *      with no explicit capability token becomes `exchange`: a round-trip mints a
+ *      capability token, and the refresh scheduler renews it before it expires.
+ *   2. Otherwise, when the caller's identity is not yet known, the result is
+ *      `pre-minted`: the capability token is used as-is. Throws `session_expired`
+ *      when there is no token to authenticate `/auth/identity`.
+ *   3. Otherwise, when the caller already knows its identity, the result is
+ *      `explicit`, with no round-trip.
  */
 export declare function resolveCredential(input: ResolveCredentialInput, ctx: ResolveCredentialContext): Promise<ResolvedCredential>;
+export {};

package/dist/auth/credentialPolicy.js

@@ -1,25 +1,18 @@
 /**
- * Credential POLICY — the single source of truth for "what KIND of credential
- * did the caller hand us, and what do we DO with it at connect time".
+ * Decides what a credential is and how to use it when a client connects. A
+ * caller configures an Ablo client with an API key, and this module answers two
+ * questions about that value: which of the four key kinds it is, and which
+ * connect-time route it takes.
  *
- * Before this module the prefix-dispatch decision (`sk_`/`ek_`/`rk_`/`pk_`) was
- * re-implemented with raw `startsWith()` sniffs in ~5 places (identity.ts ×3,
- * auth.ts browser guard, cli/dev.ts, cli/push.ts) and the connect-time routing
- * lived as a 4-branch if/elif tree inside `resolveParticipantIdentity`. Folding
- * the policy here keeps the kind-taxonomy and the connect decision in ONE place;
- * the consumers below just call into it.
+ * The routing decision is the only thing that lives here. This module does not
+ * perform the network calls that mint or exchange credentials;
+ * {@link resolveCredential} delegates those to primitives the caller supplies,
+ * so the decision of what to do stays separate from the work of doing it.
  *
- * This module is deliberately POLICY-ONLY. It does NOT own the auth primitives
- * (`exchangeApiKey` / `mintUserSessionKey` / `resolveIdentity`), the credential
- * lifecycle (`startCredentialLifecycle` / refresh scheduler), or the connection
- * FSM — those are correctly distributed consumers. `resolveCredential` DELEGATES
- * to injected primitives rather than reimplementing any HTTP mint call.
- *
- * Browser-safe: `classifyCredentialKind` is a pure-string helper and MUST NOT
- * import the Node-only `keys` module (`node:crypto`). The key-prefix contract it
- * encodes mirrors `keys/index.ts`'s `KIND_BY_PREFIX` (the Stripe-style model:
- * sk_=secret, rk_=restricted, ek_=ephemeral, pk_=publishable) but stays a plain
- * prefix lookup so it can ship in the client bundle.
+ * {@link classifyCredentialKind} is a plain string check with no Node
+ * dependencies, so it is safe to run in a browser bundle. It recognizes the key
+ * prefixes `sk_` (secret), `rk_` (restricted), `ek_` (ephemeral), and `pk_`
+ * (publishable), but does not validate a key's checksum or environment segment.
  */
 import { AbloAuthenticationError } from '../errors.js';
 const KIND_BY_PREFIX = [
@@ -29,14 +22,12 @@ const KIND_BY_PREFIX = [
     ['pk_', 'publishable'],
 ];
 /**
- * Lightweight, browser-safe prefix → kind classifier. The SINGLE source of truth
- * for prefix dispatch across the SDK (connect routing, the browser guard, the
- * CLI key-gating). Returns `null` for a value that carries no recognized Ablo
- * key prefix (a caller-supplied capability/auth token, an empty/garbage value).
- *
- * Pure string check — does NOT validate the checksum or environment segment
- * (that's `keys/index.ts` `parseApiKey`, which is Node-only). This is only the
- * "which of the four buckets" decision.
+ * Classifies a credential by its prefix, returning its {@link CredentialKind}, or
+ * `null` when the value carries no recognized Ablo key prefix — for example a
+ * capability or auth token the caller supplied, or an empty string. This is a
+ * plain string check that is safe to run in a browser; it decides only which of
+ * the four kinds a value is, and does not validate the key's checksum or
+ * environment segment.
  */
 export function classifyCredentialKind(value) {
     for (const [prefix, kind] of KIND_BY_PREFIX) {
@@ -46,34 +37,37 @@ export function classifyCredentialKind(value) {
     return null;
 }
 /**
- * Connect-time credential routing — absorbs the decision tree that used to live
- * inline in `resolveParticipantIdentity`. Classifies the configured apiKey, then
- * routes to one of four outcomes, DELEGATING the actual HTTP exchange to the
- * injected `exchangeApiKey` primitive. The caller switches on
- * `ResolvedCredential.kind` to perform scope wiring + scheduler setup.
+ * Routes a configured API key to its connect-time outcome. It classifies the
+ * key, then returns one of four {@link ResolvedCredential} variants, delegating
+ * any credential exchange to the injected `exchangeApiKey` primitive. The caller
+ * switches on the result's `kind` to wire up scope and the refresh scheduler.
  *
- * Routing (preserves the old branch order exactly):
- *   0. `pk_` + no explicit cap token → `publishable` (direct bearer, no refresh).
- *   1. exchangeable apiKey (any prefix that ISN'T a pre-minted `ek_`/`rk_`) +
- *      no explicit cap token → `exchange` (hosted-cloud round-trip + scheduler).
- *   2. otherwise, identity unknown → `pre-minted` (use the cap token as-is). Throws
- *      `session_expired` when there is no token to authenticate `/auth/identity`.
- *   3. otherwise (identity known) → `explicit` (legacy self-hosted, no round-trip).
+ * The routes, in the order they are tried:
+ *   0. A `pk_` key with no explicit capability token becomes `publishable`: used
+ *      directly as the bearer, with no refresh.
+ *   1. Any other exchangeable key (one that is not a pre-minted `ek_` or `rk_`)
+ *      with no explicit capability token becomes `exchange`: a round-trip mints a
+ *      capability token, and the refresh scheduler renews it before it expires.
+ *   2. Otherwise, when the caller's identity is not yet known, the result is
+ *      `pre-minted`: the capability token is used as-is. Throws `session_expired`
+ *      when there is no token to authenticate `/auth/identity`.
+ *   3. Otherwise, when the caller already knows its identity, the result is
+ *      `explicit`, with no round-trip.
  */
 export async function resolveCredential(input, ctx) {
     const { apiKeyValue, capabilityToken, authToken, hasExplicitIdentity } = input;
     const kind = apiKeyValue != null ? classifyCredentialKind(apiKeyValue) : null;
-    // A pre-minted capability bearer (`ek_` ephemeral / `rk_` restricted) is NOT
-    // exchangeable — it was already minted into the credential source before
-    // connect and must be USED DIRECTLY as the bearer (Route 2), never sent through
-    // `exchangeApiKey` (Route 1, which expects an `sk_`).
+    // A pre-minted capability bearer (an ephemeral `ek_` or restricted `rk_` key)
+    // is not exchangeable: it was minted before connect and is used directly as the
+    // bearer on Route 2, never sent through `exchangeApiKey`, which expects an `sk_`.
     const isPreMintedCapabilityBearer = kind === 'ephemeral' || kind === 'restricted';
     const initialCapToken = capabilityToken ??
         (isPreMintedCapabilityBearer ? apiKeyValue ?? undefined : undefined) ??
         authToken ??
         undefined;
-    // Route 0: publishable key (`pk_`) — long-lived, browser-safe, READ-ONLY. Used
-    // DIRECTLY as the bearer; never exchanged → never expires → nothing to refresh.
+    // Route 0: a publishable `pk_` key — long-lived, browser-safe, and read-only.
+    // Used directly as the bearer; it is never exchanged, so it never expires and
+    // there is nothing to refresh.
     if (apiKeyValue != null && kind === 'publishable' && capabilityToken == null) {
         return {
             kind: 'publishable',
@@ -82,8 +76,9 @@ export async function resolveCredential(input, ctx) {
             controlPlaneKey: null,
         };
     }
-    // Route 1: hosted-cloud (secret/exchangeable apiKey, no caller-supplied cap
-    // token). A pre-minted `ek_`/`rk_` is NOT exchangeable → falls through.
+    // Route 1: an exchangeable key (such as a secret `sk_`) with no caller-supplied
+    // capability token. A pre-minted `ek_` or `rk_` is not exchangeable and falls
+    // through to the next route.
     if (apiKeyValue != null &&
         capabilityToken == null &&
         !isPreMintedCapabilityBearer) {
@@ -99,15 +94,15 @@ export async function resolveCredential(input, ctx) {
             controlPlaneKey: input.configuredApiKey ?? apiKeyValue,
         };
     }
-    // Route 2: self-derived / pre-minted (use the cap token as-is). Reached when
-    // identity is NOT caller-supplied.
+    // Route 2: pre-minted — use the capability token as-is. Reached when the
+    // caller's identity was not supplied.
     if (!hasExplicitIdentity) {
         if (initialCapToken == null) {
-            // No apiKey to exchange (Route 1) and no caller-supplied identity (Route 3),
-            // so `initialCapToken` is the only thing that could authenticate
-            // `/auth/identity`. Absent — commonly the function `apiKey` resolver
-            // returning `null` (no/expired session) — surface the real, re-auth-able
-            // condition locally instead of making a doomed round-trip.
+            // With no key to exchange and no caller-supplied identity, this token is the
+            // only thing that could authenticate `/auth/identity`. When it is absent —
+            // commonly a function `apiKey` resolver returning `null` for a missing or
+            // expired session — report the re-authenticable condition here instead of
+            // making a round-trip that is bound to fail.
             throw new AbloAuthenticationError('No auth token available to resolve identity — the session token is ' +
                 'missing or expired. Ensure your `apiKey` resolver returns a valid token, or ' +
                 'pass a static `apiKey` / `capabilityToken`.', { code: 'session_expired' });
@@ -119,8 +114,8 @@ export async function resolveCredential(input, ctx) {
             controlPlaneKey: null,
         };
     }
-    // Route 3: legacy explicit (self-hosted — caller knows its own
-    // organizationId + user/agentId).
+    // Route 3: explicit — the caller already knows its own organization and user
+    // or agent id.
     return {
         kind: 'explicit',
         getBearer: initialCapToken,

package/dist/auth/credentialSource.d.ts

@@ -1,24 +1,13 @@
 /**
- * Single mutable source for the SDK's active bearer credential.
+ * The single mutable holder for the active bearer credential every transport
+ * uses.
  *
- * Every transport should read from this object at request/connect time:
- * bootstrap HTTP, lazy query HTTP, identity/probe HTTP, and WebSocket URL
- * auth. Token refresh writes here once; consumers observe the new value
- * through their getter without being manually patched one by one.
+ * Each transport reads the current token from this object at request or connect
+ * time — the HTTP request paths and the WebSocket URL authorizer alike. When the
+ * token is refreshed, it is written here once, and every reader observes the new
+ * value through its getter rather than being updated one by one.
  */
-/**
- * WebSocket subprotocols used to carry the bearer credential OUT of the URL.
- *
- * Browsers cannot set an `Authorization` header on a WebSocket, so the SDK
- * offers the token as a `Sec-WebSocket-Protocol` value — `ablo.bearer.<token>` —
- * alongside the real `ablo.sync.v1` protocol the server selects. This keeps the
- * credential out of the query string, which ALB access logs, proxies, and
- * browser history capture. The server reads the token from the subprotocol and
- * echoes back ONLY `ablo.sync.v1`, never the token-bearing value. Shared with
- * the sync-server so client and server can never drift on the wire format.
- */
-export declare const WS_BEARER_SUBPROTOCOL_PREFIX = "ablo.bearer.";
-export declare const WS_SYNC_SUBPROTOCOL = "ablo.sync.v1";
+export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from '../wire/protocol.js';
 export interface AuthCredentialSource {
     getAuthToken(): string | null;
     setAuthToken(token: string | null | undefined): void;