@abloatai/transaction 0.59.2 → 0.60.0

package/src/transport/http/transport.ts

@@ -28,6 +28,7 @@ import {
   readProcessEnv,
   resolveApiKey,
   resolveApiKeyValue,
+  resolveCredentialValue,
   resolveAuthToken,
   resolveBaseURL,
   resolveBootstrapBaseUrl,
@@ -86,15 +87,10 @@ import type {
   HttpTransportList,
   HttpLogsResource,
   ModelTarget,
-  CreateSessionParams,
-  AbloSession,
-  SessionResource,
 } from '../../client/resources/httpResources.js';
-import { mintSession } from '../../auth/sessionMint.js';
-import {
-  revokeCapability,
-  rotateCapability,
-} from '../../auth/capabilityLifecycle.js';
+import type { CredentialProviderResult } from '../../auth/credentialResult.js';
+import { credentialToken } from '../../auth/credentialResult.js';
+import { createSessionAccess, type SessionAccess } from '../../sessions/index.js';
 import { parseIdentityResolveResponse } from '../../auth/schemas.js';
 import type { EffectiveAuthority } from '../../auth/capability.js';
 
@@ -103,7 +99,6 @@ import {
   heldHeartbeatReply,
   parseSuccessfulCommitResponse,
 } from './helpers.js';
-import type { SchemaRecord } from '../../schema/schema.js';
 import type {
   ClaimLookupParams,
   ClaimOptions,
@@ -180,8 +175,6 @@ import type { CommitFrameOperation } from '../websocket/commitFrames.js';
 /** @internal Private options for the schema-agnostic HTTP protocol transport. */
 export type HttpTransportOptions = Omit<HttpClientConfig, 'schema'> & {
   readonly bootstrapBaseUrl?: string | undefined;
-  /** Schema-key to wire-typename mapping used only when minting agent sessions. */
-  readonly modelTypenames?: Readonly<Record<string, string>> | undefined;
   /**
    * The observability provider forwarded from `Ablo({ observability })`. The HTTP
    * transport emits the same claim and conflict events as the WebSocket transport,
@@ -221,9 +214,6 @@ export type HttpTransportOptions = Omit<HttpClientConfig, 'schema'> & {
 /** @internal Default per-request deadline for the private HTTP transport. */
 export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const HTTP_CONFIRMATION_POLL_INTERVAL_MS = 250;
-// NOTE: end-user / agent session minting is `ablo.sessions.create(...)` (typed
-// against the schema, see Ablo.ts `CreateSessionParams`). There is no separate
-// `ephemeralKeys` resource — `sessions` is the one front door for both.
 
 /** @internal Private protocol surface wrapped by `AbloHttpClient`. */
 export interface HttpTransport {
@@ -255,12 +245,8 @@ export interface HttpTransport {
    * server with the credential this client already holds — no re-mint.
    */
   getAuthToken(): Promise<string | null>;
-  /**
-   * Mint a short-lived scoped session. Minting is a control-plane HTTP call (no
-   * socket), so it lives on this stateless client too, not only the realtime one.
-   * `{ user }` mints an `ek_`; `{ agent, can }` mints an `rk_`.
-   */
-  readonly sessions: SessionResource<SchemaRecord>;
+  /** @internal One normalized source shared by HTTP bootstrap and live transport. */
+  readonly access: SessionAccess;
 }
 
 type CommitResponse = CommitReceiptWire;
@@ -466,6 +452,12 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     return headers;
   }
 
+  async function activeCredential(): Promise<CredentialProviderResult> {
+    return (await resolveCredentialValue(configuredApiKey)) ?? configuredAuthToken ?? null;
+  }
+
+  const access = createSessionAccess(options.session, activeCredential);
+
   function endpoint(path: string): string {
     const target = new URL(`${apiBaseUrl}${path.startsWith('/') ? path : `/${path}`}`);
     for (const [key, value] of Object.entries(options.defaultQuery ?? {})) {
@@ -2222,64 +2214,12 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     claims,
     logs,
     model,
-    sessions: {
-      async create(params: CreateSessionParams<SchemaRecord>): Promise<AbloSession> {
-        // Stateless mint: the configured key is the control-plane credential here
-        // (no startup `rk_` exchange runs on this client). It reuses the resolved
-        // base URL and fetch; the shared `mintSession` handles the two server routes.
-        const apiKey = await resolveApiKeyValue(configuredApiKey);
-        if (!apiKey) {
-          throw new AbloAuthenticationError(
-            'sessions.create requires a secret (sk_) API key — call it from your backend, not the browser.',
-            { code: 'apikey_missing' }
-          );
-        }
-        // A transport built without a schema has no way to translate `can`'s
-        // schema keys into the type names the server gates on. Minting anyway
-        // would spell every override wrong and surface as
-        // `capability_scope_denied` on the agent's first write, so refuse here
-        // instead of guessing.
-        if (!options.modelTypenames) {
-          throw new AbloValidationError(
-            'sessions.create needs the schema this client is bound to. Construct it ' +
-              "through Ablo({ schema, apiKey, transport: 'http' }) rather than the " +
-              'bare transport.',
-            { code: 'invalid_options', param: 'schema' },
-          );
-        }
-        return mintSession(params, {
-          apiKey,
-          baseUrl: apiBaseUrl,
-          modelTypenames: options.modelTypenames,
-          ...(options.fetch ? { fetch: options.fetch } : {}),
-        });
-      },
-      async revoke({ id }) {
-        const apiKey = await resolveApiKeyValue(configuredApiKey);
-        return revokeCapability({
-          apiKey: apiKey ?? '',
-          baseUrl: apiBaseUrl,
-          id,
-          ...(options.fetch ? { fetch: options.fetch } : {}),
-        });
-      },
-      async rotate({ id, graceSeconds, ttlSeconds }) {
-        const apiKey = await resolveApiKeyValue(configuredApiKey);
-        return rotateCapability({
-          apiKey: apiKey ?? '',
-          baseUrl: apiBaseUrl,
-          id,
-          ...(graceSeconds !== undefined ? { graceSeconds } : {}),
-          ...(ttlSeconds !== undefined ? { ttlSeconds } : {}),
-          ...(options.fetch ? { fetch: options.fetch } : {}),
-        });
-      },
-    },
     async getAuthToken(): Promise<string | null> {
       // Mirror `authHeaders()`: a configured API key wins, else the
       // construction-time auth token. Resolve the (possibly async) key setter.
-      return (await resolveApiKeyValue(configuredApiKey)) ?? configuredAuthToken ?? null;
+      return credentialToken(await activeCredential());
     },
+    access,
   };
 }
 

package/src/transport/websocket/commitFrames.ts

@@ -17,7 +17,6 @@ import type {
   ClaimQueued,
   ClaimLost,
   ClaimRejection,
-  ClaimExpired,
 } from '../../coordination/schema.js';
 import type { ClaimEvent, ClaimCounterparty } from '../../claims/events.js';
 import type { AssertExact } from '../../types/assertExact.js';
@@ -105,7 +104,6 @@ interface ClaimFrameByPhase {
   queued: ClaimQueued;
   lost: ClaimLost;
   rejected: ClaimRejection;
-  expired: ClaimExpired;
 }
 
 // The phases this map covers and the phases a ClaimEvent can report are the

package/src/transport/websocket/frameHandlers.ts

@@ -45,16 +45,6 @@ export interface PendingCommit {
   readonly returnReceipt?: boolean;
 }
 
-/**
- * In-flight `claim` request record, keyed by claimId. Resolved when the
- * matching `claim_ack` arrives, or rejected on timeout/disconnect.
- */
-export interface PendingClaim {
-  resolve: (value: { syncGroups: string[]; ttlSeconds?: number }) => void;
-  reject: (err: Error) => void;
-  timeout: ReturnType<typeof setTimeout>;
-}
-
 /**
  * An in-flight `update_subscription` request awaiting its
  * `subscription_ack`. The wire carries no correlation id, so requests are
@@ -109,8 +99,6 @@ export interface WsSession {
   observability: SocketObservability;
   /** In-flight commit acks keyed by clientTxId. */
   pendingMutations: Map<string, PendingCommit>;
-  /** In-flight claim acks keyed by claimId. */
-  pendingClaims: Map<string, PendingClaim>;
   /** Removes and returns the oldest in-flight `update_subscription` request. */
   shiftPendingSubscription(): PendingSubscription | undefined;
   /** Connection options subset the handlers write back (acked sync groups). */
@@ -290,84 +278,6 @@ const handleMutationResult: WsFrameHandler = (session, message) => {
   }
 };
 
-/**
- * Handles the acknowledgement of a `claim` request. The frame has the shape
- * `{ type: 'claim_ack', payload: { claimId, success, syncGroups?,
- * ttlSeconds?, error? } }`.
- */
-const handleClaimAck: WsFrameHandler = (session, message) => {
-  const p = (message.payload ?? {}) as Record<string, unknown>;
-  const { claimId, success, syncGroups, ttlSeconds, error } = p;
-  const pending =
-    typeof claimId === 'string'
-      ? session.pendingClaims.get(claimId)
-      : undefined;
-  if (!pending) return;
-  clearTimeout(pending.timeout);
-  // `pending` exists ⇒ claimId was a string key (the guard above).
-  session.pendingClaims.delete(claimId as string);
-  if (success) {
-    pending.resolve({
-      syncGroups: Array.isArray(syncGroups) ? syncGroups : [],
-      ttlSeconds: typeof ttlSeconds === 'number' ? ttlSeconds : undefined,
-    });
-  } else {
-    const err = error as
-      | {
-          code?: unknown;
-          message?: unknown;
-          request_id?: unknown;
-          event_id?: unknown;
-        }
-      | undefined;
-    const code =
-      err?.code && typeof err.code === 'string'
-        ? err.code
-        : 'claim_rejected';
-    const msg =
-      err?.message && typeof err.message === 'string'
-        ? err.message
-        : 'claim rejected by server';
-    const requestId =
-      typeof err?.request_id === 'string' ? err.request_id : undefined;
-    const eventId =
-      typeof err?.event_id === 'string' ? err.event_id : undefined;
-    const details = eventId === undefined ? undefined : { event_id: eventId };
-    // Capability denials get the typed CapabilityError so
-    // callers can read `.requiredCapability` and attenuate-
-    // and-retry the claim with a narrower token.
-    if (
-      code === 'capability_scope_denied' ||
-      code === 'capability_invalid'
-    ) {
-      const rc = (error as { requiredCapability?: unknown } | undefined)
-        ?.requiredCapability;
-      const requiredCapability =
-        rc != null &&
-        typeof rc === 'object' &&
-        typeof (rc as { scope?: unknown }).scope === 'string'
-          ? (rc as RequiredCapability)
-          : undefined;
-      pending.reject(
-        new CapabilityError(code, msg, requiredCapability, {
-          ...(requestId !== undefined ? { requestId } : {}),
-          ...(details !== undefined ? { details } : {}),
-        }),
-      );
-    } else {
-      // Route through the shared factory so a failed claim_ack is a
-      // typed AbloError (registry code → right subclass), symmetric
-      // with the commit `mutation_result` path — never a bare Error.
-      pending.reject(
-        errorFromWire(msg, {
-          code,
-          requestId,
-          details,
-        }),
-      );
-    }
-  }
-};
 
 /**
  * Handles the acknowledgement of an `update_subscription` request. The wire
@@ -448,7 +358,6 @@ export const wsFrameHandlers: Record<string, WsFrameHandler> = {
   bootstrap_response: (session, message) => { session.handleBootstrapResponse(message.payload); },
   presence_update: (session, message) => { session.handlePresenceUpdate(message); },
   mutation_result: handleMutationResult,
-  claim_ack: handleClaimAck,
   subscription_ack: handleSubscriptionAck,
   delta: handleDeltaFrame,
 };
@@ -497,17 +406,6 @@ const validatedFrameHandlers: Record<
       session.handlePresenceUpdate({ payload });
     },
   ),
-  claim_expired: validating(
-    WS_INBOUND_FRAMES.claim_expired.payload,
-    'claim_expired',
-    (session, payload) => {
-      // Server-initiated expiry. The claim is already inactive by the time
-      // this arrives, so a consumer either re-claims with a fresh credential
-      // or accepts the drop.
-      recordClaim(tracePorts(session), 'expired', payload);
-      session.emit('claim_expired', payload);
-    },
-  ),
   claim_rejected: validating(
     WS_INBOUND_FRAMES.claim_rejected.payload,
     'claim_rejected',

package/src/transport/websocket/session.ts

@@ -3,7 +3,14 @@ import {
   AbloConnectionError,
   AbloSessionError,
   errorFromWire,
+  isAccessCredentialExpiryCloseReason,
 } from '../../errors.js';
+import { classifyCredentialKind } from '../../auth/credentialKind.js';
+import {
+  credentialToken,
+  type CredentialProviderResult,
+} from '../../auth/credentialResult.js';
+import { CredentialLifecycle } from '../../sessions/lifecycle.js';
 import {
   clientSyncDeltaSchema,
   type ClientSyncDelta,
@@ -21,7 +28,6 @@ import type {
   WebSocketObserveOptions,
   WebSocketObservedDelta,
   WebSocketPresence,
-  WebSocketJoinInput,
   WebSocketSessionOptions,
   OpenCollaborationEvents,
 } from './sessionContract.js';
@@ -125,17 +131,29 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
   private closed = false;
   private currentToken: string;
   private acknowledgeLane: Promise<void> = Promise.resolve();
+  private terminalError: Error | null = null;
+  private readonly terminalListeners = new Set<(error: Error) => void>();
+  private readonly credentialLifecycle: CredentialLifecycle | null;
+  private pendingSessionError: Error | null = null;
 
   readonly presence: WebSocketPresence;
   readonly collaboration: WebSocketCollaboration<TEvents>;
 
-  constructor(options: WebSocketSessionOptions, position: StoredPosition, token: string) {
+  constructor(
+    options: WebSocketSessionOptions,
+    position: StoredPosition,
+    credential: CredentialProviderResult,
+  ) {
     this.options = options;
+    const token = credentialToken(credential);
+    if (!token) {
+      throw new AbloSessionError('The WebSocket transport requires an authenticated credential.');
+    }
     this.currentToken = token;
     this.cursorKey = options.cursorKey ?? 'websocket';
     this.socket = new AgentWebSocket<TEvents>({
       baseUrl: options.baseUrl,
-      kind: 'agent',
+      kind: classifyCredentialKind(token) === 'ephemeral' ? 'user' : 'agent',
       getAuthToken: () => this.currentToken,
       syncGroups: [...(options.syncGroups ?? [])],
       collaborationEvents: [...(options.collaborationEvents ?? [])],
@@ -148,23 +166,65 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
     this.collaboration = {
       send: (event, payload) => this.socket.sendCollaborationEvent(event, payload),
     } as WebSocketCollaboration<TEvents>;
-    this.socket.subscribe('session_error', () => {
-      void this.refreshExpiredCredential();
+    this.socket.subscribe('session_error', (error) => {
+      this.handleSessionError(error);
     });
+    this.credentialLifecycle = options.access.renewable
+      ? new CredentialLifecycle({
+        setAuthToken: (freshToken) => {
+          this.currentToken = freshToken;
+        },
+        nudgeReconnect: () => {
+          if (this.closed || this.terminalError) return;
+          this.socket.clearSessionError();
+          this.socket.resetReconnectAttempts();
+          this.socket.connect();
+        },
+        reportSessionExpired: () => {
+          this.failTerminal(this.pendingSessionError ?? new AbloSessionError(
+            'The application session ended while renewing its Ablo session.',
+          ));
+        },
+      })
+      : null;
+    if (this.credentialLifecycle) {
+      this.credentialLifecycle.start(() => this.loadCredential(), { proactiveInNode: true });
+      this.credentialLifecycle.accept(credential);
+    }
   }
 
-  private async refreshExpiredCredential(): Promise<void> {
-    if (this.closed) return;
-    try {
-      const next = await this.options.getAuthToken();
-      if (!next || next === this.currentToken) return;
-      this.currentToken = next;
-      this.socket.clearSessionError();
-      this.socket.connect();
-    } catch {
-      // The terminal session_error remains the public signal. A later explicit
-      // ready() call can retry after the caller repairs its credential source.
+  private async loadCredential(): Promise<CredentialProviderResult> {
+    return this.options.access.credential();
+  }
+
+  private handleSessionError(error: Error): void {
+    if (
+      !this.credentialLifecycle
+      || !isAccessCredentialExpiryCloseReason(error.message)
+    ) {
+      this.failTerminal(error);
+      return;
     }
+    this.pendingSessionError = error;
+    void this.credentialLifecycle.recoverFromAuthRejection('access_credential_expiry');
+  }
+
+  private failTerminal(error: Error): void {
+    if (this.terminalError || this.closed) return;
+    this.terminalError = error;
+    this.socket.setSessionErrorDetected();
+    this.socket.disconnect();
+    for (const listener of this.terminalListeners) listener(error);
+  }
+
+  private onTerminal(listener: (error: Error) => void): () => void {
+    if (this.terminalError) {
+      const error = this.terminalError;
+      queueMicrotask(() => listener(error));
+      return () => undefined;
+    }
+    this.terminalListeners.add(listener);
+    return () => this.terminalListeners.delete(listener);
   }
 
   get connected(): boolean {
@@ -175,6 +235,7 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
     if (this.closed) {
       return Promise.reject(new AbloConnectionError('The WebSocket session is closed.'));
     }
+    if (this.terminalError) return Promise.reject(this.terminalError);
     if (this.socket.isConnected()) return Promise.resolve();
     if (this.readyPromise) return this.readyPromise;
     this.readyPromise = new Promise<void>((resolve, reject) => {
@@ -190,7 +251,7 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
         cleanup();
         resolve();
       });
-      const failed = this.socket.subscribe('session_error', (error) => {
+      const failed = this.onTerminal((error) => {
         rejectConnection(error);
       });
       const mismatch = this.socket.subscribe('protocol_mismatch', () => {
@@ -311,19 +372,6 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
     this.socket.send({ type: 'claim_abandon', payload: input });
   }
 
-  async join(input: WebSocketJoinInput) {
-    await this.ready();
-    return this.socket.sendClaim(input.claimId, input.syncGroups, {
-      capabilityToken: input.capabilityToken,
-      ttlSeconds: input.ttlSeconds,
-      timeoutMs: input.timeoutMs,
-    });
-  }
-
-  leave(claimId: string): void {
-    this.socket.sendRelease(claimId);
-  }
-
   subscribe<K extends keyof SyncWebSocketEventMap<TEvents>>(
     event: K,
     listener: (...args: SyncWebSocketEventMap<TEvents>[K]) => void,
@@ -357,7 +405,7 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
       wake?.();
       wake = undefined;
     });
-    const offError = this.socket.subscribe('session_error', (error) => {
+    const offError = this.onTerminal((error) => {
       failure = error;
       wake?.();
       wake = undefined;
@@ -421,6 +469,8 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
   async close(): Promise<void> {
     if (this.closed) return;
     this.closed = true;
+    this.credentialLifecycle?.stop();
+    this.terminalListeners.clear();
     this.rejectReady?.(new AbloConnectionError('The WebSocket session was disposed.'));
     await this.acknowledgeLane;
     this.socket.disconnect();
@@ -439,11 +489,16 @@ export async function createWebSocketSession<
 ): Promise<AbloWebSocketSession<TEvents>> {
   const cursorKey = options.cursorKey ?? 'websocket';
   const stored = await options.cursorStore?.load(cursorKey) ?? null;
-  const token = await options.getAuthToken();
+  const credential = await options.access.credential();
+  const token = credentialToken(credential);
   if (!token) {
     throw new AbloSessionError('The WebSocket transport requires an authenticated credential.');
   }
-  const session = new WebSocketSession<TEvents>(options, parsePosition(stored), token);
+  const session = new WebSocketSession<TEvents>(
+    options,
+    parsePosition(stored),
+    credential,
+  );
   let rejectOpening: ((error: Error) => void) | undefined;
   const aborted = new Promise<never>((_resolve, reject) => {
     rejectOpening = reject;

package/src/transport/websocket/sessionContract.ts

@@ -8,6 +8,7 @@ import type {
 } from '../../coordination/schema.js';
 import type { ClientSyncDelta } from '../../observation/contract.js';
 import type { ObserveCursorStore } from '../../client/contract.js';
+import type { SessionAccess } from '../../sessions/source.js';
 import type { CommitFrameOperation } from '../websocket/commitFrames.js';
 import type {
   CoreSyncEventMap,
@@ -18,7 +19,8 @@ import type {
 
 export interface WebSocketSessionOptions {
   readonly baseUrl?: string;
-  readonly getAuthToken: () => string | undefined | Promise<string | undefined>;
+  /** Normalized once at the client boundary; transports do not infer policy. */
+  readonly access: SessionAccess;
   readonly syncGroups?: readonly string[];
   readonly collaborationEvents?: readonly string[];
   readonly cursorKey?: string;
@@ -44,15 +46,6 @@ export interface WebSocketObserveOptions {
   readonly signal?: AbortSignal;
 }
 
-/** A multiplexed participant-scope registration on the shared socket. */
-export interface WebSocketJoinInput {
-  readonly claimId: string;
-  readonly syncGroups: readonly string[];
-  readonly capabilityToken?: string;
-  readonly ttlSeconds?: number;
-  readonly timeoutMs?: number;
-}
-
 /** A durable row/field claim carried over the same live protocol. */
 export type WebSocketClaimInput = ClaimBeginPayload & {
   readonly timeoutMs?: number;
@@ -95,8 +88,6 @@ export interface AbloWebSocketSession<
     readonly entityType?: string;
     readonly entityId?: string;
   }): void;
-  join(input: WebSocketJoinInput): Promise<{ syncGroups: string[]; ttlSeconds?: number }>;
-  leave(claimId: string): void;
   subscribe<K extends keyof SyncWebSocketEventMap<TEvents>>(
     event: K,
     listener: (...args: SyncWebSocketEventMap<TEvents>[K]) => void,