@abloatai/ablo 0.7.0 → 0.9.0

package/dist/client/Ablo.js

@@ -11,17 +11,22 @@
  *   const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
  *
  *   const reports = sync.reports.list({ where: { status: 'todo' } });
- *   await sync.reports.create({ title: 'Fix bug' });
- *   await sync.reports.update(reportId, { status: 'ready' });
- *   await sync.reports.delete(reportId);
+ *   await sync.reports.create({ data: { title: 'Fix bug' } });
+ *   await sync.reports.update({
+ *     id: reportId,
+ *     data: { status: 'ready' },
+ *   });
+ *   await sync.reports.delete({ id: reportId });
  */
 import { z } from 'zod';
-import { AbloClaimedError, AbloError, AbloConnectionError, AbloValidationError, translateHttpError } from '../errors.js';
+import { AbloClaimedError, AbloError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, translateHttpError, hasWireCode, toAbloError } from '../errors.js';
 import { LoadStrategy, PropertyType } from '../types/index.js';
 import { initSyncEngine } from '../context.js';
 import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, noopAnalytics, } from '../SyncEngineContext.js';
 import { alwaysOnline } from '../adapters/alwaysOnline.js';
 import { validateAbloOptions } from './validateAbloOptions.js';
+import { exchangeApiKey } from '../auth/index.js';
+import { createAuthCredentialSource } from '../auth/credentialSource.js';
 import { createInternalComponents } from './createInternalComponents.js';
 import { resolveParticipantIdentity } from './identity.js';
 import { Model } from '../Model.js';
@@ -32,7 +37,8 @@ import { awaitIntentGrant } from '../sync/awaitIntentGrant.js';
 import { createSnapshot } from '../sync/createSnapshot.js';
 import { createParticipantManager } from '../sync/participants.js';
 import { createProtocolClient, } from './ApiClient.js';
-import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveAuthToken, resolveBaseURL, } from './auth.js';
+import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, } from './auth.js';
+import { registerDataSource } from './registerDataSource.js';
 import { shouldUseInMemoryPersistence, } from './persistence.js';
 import { createModelProxy } from './createModelProxy.js';
 // ── Config derivation from schema ─────────────────────────────────────────
@@ -644,6 +650,37 @@ function createDefaultMutationDispatcher(executor) {
         },
     };
 }
+// ── Auth normalization ─────────────────────────────────────────────────────
+/**
+ * The one resolver the credential lifecycle needs: an async `() => token | null`,
+ * or `null` when auth is static (a plain long-lived `apiKey` with no refresh —
+ * the common case). Only the short-lived per-user path sets this, via `getToken`
+ * (the primitive) or `authEndpoint` (sugar that POSTs for `{ token }`).
+ */
+function resolveCredentialResolver(options) {
+    if (options.getToken)
+        return options.getToken;
+    if (options.authEndpoint) {
+        const endpoint = options.authEndpoint;
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        return async () => {
+            // The endpoint lives on the consumer's OWN backend and is authed by the
+            // user's session cookie (hence `credentials: 'include'`); it returns the
+            // `ek_` to carry to the sync-server. A non-OK response is terminal
+            // (`null` → sign out), matching the `getToken` contract.
+            const res = await fetchImpl(endpoint, {
+                method: 'POST',
+                credentials: 'include',
+                headers: { 'Content-Type': 'application/json' },
+            });
+            if (!res.ok)
+                return null;
+            const body = (await res.json());
+            return body.token ?? null;
+        };
+    }
+    return null;
+}
 export function Ablo(options) {
     if (options.schema == null) {
         return createProtocolClient(options);
@@ -653,8 +690,16 @@ export function Ablo(options) {
     const authInput = { options, env };
     const configuredApiKey = resolveApiKey(authInput);
     const configuredAuthToken = resolveAuthToken(authInput);
+    // The client OWNS its credential lifecycle (not the React layer): this resolver
+    // drives both the reactive re-mint (FSM `credential_stale`) and the proactive
+    // refresh timer + wake/online/focus triggers. Null for the common static
+    // `apiKey` path — no refresh needed.
+    const credentialResolver = resolveCredentialResolver(options);
+    const authCredentials = createAuthCredentialSource(internalOptions.capabilityToken ?? configuredAuthToken);
+    const configuredDatabaseUrl = resolveDatabaseUrl(authInput);
     assertBrowserSafety({
         apiKey: configuredApiKey,
+        databaseUrl: configuredDatabaseUrl,
         dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
     });
     const { logger = consoleLogger } = internalOptions;
@@ -720,7 +765,12 @@ export function Ablo(options) {
     //    the schema-to-Model-class translation depends on private
     //    helpers (`createDynamicModelClass`, `unwrapZodType`, etc.)
     //    that aren't worth pulling into the components module.
-    const { modelRegistry, objectPool, bootstrapHelper, database, syncClient, hydration, } = createInternalComponents({ schema, url, options: internalOptions });
+    const { modelRegistry, objectPool, bootstrapHelper, database, syncClient, hydration, } = createInternalComponents({
+        schema,
+        url,
+        options: internalOptions,
+        auth: authCredentials,
+    });
     registerModelsFromSchema(schema, modelRegistry);
     // 5. BaseSyncedStore handles the initialization orchestration
     //    (open DB → hydrate IDB → connect WS → fetch bootstrap → hydrate again →
@@ -738,7 +788,15 @@ export function Ablo(options) {
         modelRegistry,
         schema,
         url,
+        auth: authCredentials,
     });
+    // Hand the credential lifecycle to the client (refresher + proactive refresh
+    // timer + wake/online/focus re-mint). Installed once here so refresh works for
+    // ANY consumer of `Ablo({ auth })` — not only those who render `<AbloProvider>`.
+    // The first mint happens in `ready()` so the first connection carries a token.
+    if (credentialResolver) {
+        store.startCredentialLifecycle(credentialResolver);
+    }
     // Wire the store back into the default executor's lazy getter (see
     // `storeHolder` above). The executor was constructed before the store
     // existed; this late binding closes the loop so commits dispatch over
@@ -808,16 +866,6 @@ export function Ablo(options) {
     //    source of truth. No duplicate closure variables.
     let _readyPromise = null;
     let _refreshScheduler = null;
-    let currentCapabilityToken = internalOptions.capabilityToken ?? configuredAuthToken ?? undefined;
-    // Wire the cap token into HydrationCoordinator's HTTP path. Without
-    // this, `ablo.<model>.load(...)` / `ablo.<model>.retrieve(...)` go
-    // through `postQuery` with `credentials: 'include'` only — fine in
-    // browsers (session cookies), but Node consumers (agent-worker)
-    // have no cookies and the request lands with no credential at all.
-    // The WS path was already wired (token rides the upgrade URL); this
-    // closes the gap on HTTP. Closure-over-binding so cap rotation
-    // (`applyRotatedToken` in the refresh scheduler below) propagates.
-    hydration.setCapabilityTokenProvider(() => currentCapabilityToken ?? null);
     async function ready() {
         if (_readyPromise)
             return _readyPromise;
@@ -827,6 +875,33 @@ export function Ablo(options) {
         }
         _readyPromise = (async () => {
             try {
+                // Mint the FIRST access credential before we connect, so the initial
+                // WebSocket upgrade + bootstrap carry a valid bearer (no tokenless first
+                // connect that has to self-heal). Only when a refreshing resolver is
+                // wired AND no static credential is already present. Contract mirrors
+                // `getToken`: `null` ⇒ the login is gone (terminal — fail ready so the
+                // app shows sign-in); a THROW ⇒ transient (rethrown; autoStart swallows
+                // and the lifecycle's online/wake triggers retry).
+                if (credentialResolver && !authCredentials.getAuthToken()) {
+                    const token = await credentialResolver();
+                    if (!token) {
+                        throw new AbloAuthenticationError('Auth resolver returned null before connect — the user is not signed in.', { code: 'auth_no_credentials' });
+                    }
+                    authCredentials.setAuthToken(token);
+                }
+                // Register the caller's own database for write-back BEFORE bootstrap, so
+                // the server resolves this org's data plane to the customer's DB rather
+                // than serving an empty/wrong store. The org is derived server-side from
+                // the API key. Idempotent server-side (register-or-update). Skipped when
+                // no `databaseUrl` was configured (Ablo-managed storage).
+                if (configuredDatabaseUrl) {
+                    await registerDataSource({
+                        baseUrl: resolveBootstrapBaseUrl({ url }),
+                        apiKey: await resolveApiKeyValue(configuredApiKey),
+                        databaseUrl: configuredDatabaseUrl,
+                        ...(internalOptions.fetch ? { fetchImpl: internalOptions.fetch } : {}),
+                    });
+                }
                 // Resolve participant identity + scope. Three branches —
                 // hosted-cloud apiKey exchange, self-derived from capability
                 // token, or legacy explicit options. See `./identity.ts`.
@@ -836,15 +911,18 @@ export function Ablo(options) {
                     url,
                     kind,
                     configuredApiKey,
-                    configuredAuthToken,
+                    // Resolve identity against the LIVE token, not the construction-time
+                    // `configuredAuthToken`. Consumers using `getToken` (apps/web) never
+                    // pass `authToken` at construction — they call `setAuthToken()` before
+                    // `ready()`, which updates the shared credential source. Reading the frozen
+                    // `configuredAuthToken` here made `/auth/identity` fire with no Bearer
+                    // (→ `no_matching_provider` / `session_expired`) even though the JWT
+                    // was present. Mirrors every other transport by reading the shared
+                    // credential source.
+                    configuredAuthToken: authCredentials.getAuthToken() ?? configuredAuthToken,
                     bootstrapHelper,
+                    auth: authCredentials,
                     logger,
-                    applyRotatedToken: (token) => {
-                        currentCapabilityToken = token;
-                        bootstrapHelper.setAuthToken(token);
-                        const ws = store.getSyncWebSocket();
-                        ws?.setCapabilityToken(token);
-                    },
                 });
                 const { userId, accountScope, teamIds, capabilityToken, syncGroups, participantKind, } = resolved;
                 // Fail-loud guard: detect the degenerate "no real sync groups
@@ -870,8 +948,6 @@ export function Ablo(options) {
                         '`["org:${orgId}", "user:${userId}"]`) or verify your auth ' +
                         'provider populates them. See packages/sync-engine/src/client/identity.ts.', { participantKind, resolvedSyncGroups });
                 }
-                currentCapabilityToken = capabilityToken;
-                bootstrapHelper.setAuthToken(capabilityToken);
                 if (resolved.refreshScheduler) {
                     _refreshScheduler = resolved.refreshScheduler;
                 }
@@ -902,7 +978,11 @@ export function Ablo(options) {
                 }
                 const result = current.value;
                 if (!result.success) {
-                    throw result.error ?? new Error('Sync engine initialization failed');
+                    throw result.error
+                        ? toAbloError(result.error)
+                        : new AbloConnectionError('Sync engine initialization failed', {
+                            code: 'bootstrap_fetch_timeout',
+                        });
                 }
                 // Wire presence + intents to the now-open transport.
                 // `getSyncWebSocket()` returns non-null after a successful
@@ -916,11 +996,33 @@ export function Ablo(options) {
                 logger.info('Sync engine ready', { models: Object.keys(schema.models).length });
             }
             catch (err) {
-                const error = err instanceof Error ? err : new Error(String(err));
+                // Coerce so the rejection a consumer awaiting `ready()` catches is
+                // always an AbloError — connection setup is held to the same
+                // never-leak-untagged contract as the model operations.
+                const error = toAbloError(err);
                 // Make sure syncStatus reflects the failure for observer() components
                 store.syncStatus.state = 'error';
                 store.syncStatus.error = error;
-                logger.error('Sync engine failed to initialize', { error: error.message });
+                // Log the typed envelope (type + code + status), not just the bare
+                // message — so the console line names it as an Ablo error and carries
+                // the code (e.g. AbloAuthenticationError/identity_resolve_failed on a
+                // 401) instead of reading like an untagged failure.
+                logger.error('Sync engine failed to initialize', {
+                    type: error.type,
+                    code: error.code,
+                    httpStatus: error.httpStatus,
+                    error: error.message,
+                });
+                // Clear the memo so a FUTURE `ready()` re-attempts bootstrap instead of
+                // replaying this rejection forever. Bootstrap failures here are
+                // transient by nature — offline, an IndexedDB open timeout, a bootstrap
+                // fetch hiccup — and used to brick the engine until a full page reload
+                // because line ~2013 (`if (_readyPromise) return _readyPromise`) handed
+                // every later caller this same dead promise. Nulling it lets the
+                // provider's online/wake/retry triggers drive a clean re-bootstrap.
+                // (The terminal `_validationError` branch above intentionally stays
+                // cached — config can't change without recreating the engine.)
+                _readyPromise = null;
                 throw error;
             }
         })();
@@ -951,14 +1053,7 @@ export function Ablo(options) {
     }
     const fetchImpl = options.fetch ?? globalThis.fetch;
     function authHeaders() {
-        const headers = { 'Content-Type': 'application/json' };
-        if (currentCapabilityToken) {
-            headers.Authorization = `Bearer ${currentCapabilityToken}`;
-        }
-        else if (configuredAuthToken) {
-            headers.Authorization = `Bearer ${configuredAuthToken}`;
-        }
-        return headers;
+        return authCredentials.withAuthHeaders({ 'Content-Type': 'application/json' });
     }
     function createClientTxId(idempotencyKey) {
         if (idempotencyKey && idempotencyKey.length > 0)
@@ -1007,11 +1102,15 @@ export function Ablo(options) {
         return inputOperations.map((op) => normalizeCommitOperation(op, commitOptions));
     }
     function modelClaimFromActive(intent) {
+        const description = typeof intent.target.meta?.description === 'string'
+            ? intent.target.meta.description
+            : undefined;
         return {
             id: intent.id,
             actor: intent.heldBy,
             participantKind: intent.participantKind,
             action: intent.reason,
+            ...(description ? { description } : {}),
             field: intent.target.field,
             status: 'active',
             expiresAt: intent.expiresAt,
@@ -1031,6 +1130,7 @@ export function Ablo(options) {
             actor: intent.heldBy,
             participantKind: intent.participantKind,
             action: intent.action,
+            ...(intent.description ? { description: intent.description } : {}),
             field: intent.target.field,
             status: 'queued',
             position: intent.position,
@@ -1279,7 +1379,6 @@ export function Ablo(options) {
         const res = await fetchImpl(`${bootstrapHelper.baseUrl}/sync/query`, {
             method: 'POST',
             headers: authHeaders(),
-            credentials: 'include',
             body: JSON.stringify({
                 queries: [
                     {
@@ -1321,59 +1420,59 @@ export function Ablo(options) {
     }
     function model(name) {
         return {
-            retrieve(id, options) {
-                return retrieveModel(name, id, options);
+            retrieve(params) {
+                return retrieveModel(name, params.id, params);
             },
-            async create(data, mutationOptions) {
-                const id = mutationOptions?.id ?? createModelId();
-                await applyClaimedPolicy({ model: name, id }, mutationOptions);
+            async create(params) {
+                const id = params.id ?? createModelId();
+                await applyClaimedPolicy({ model: name, id }, params);
                 return commits.create({
-                    intent: mutationOptions?.intent,
-                    idempotencyKey: mutationOptions?.idempotencyKey,
-                    readAt: mutationOptions?.readAt,
-                    onStale: mutationOptions?.onStale,
-                    wait: mutationOptions?.wait,
+                    intent: params.intent,
+                    idempotencyKey: params.idempotencyKey,
+                    readAt: params.readAt,
+                    onStale: params.onStale,
+                    wait: params.wait,
                     operations: [
                         {
                             action: 'create',
                             model: name,
                             id,
-                            data,
+                            data: params.data,
                         },
                     ],
                 });
             },
-            async update(id, data, mutationOptions) {
-                await applyClaimedPolicy({ model: name, id }, mutationOptions);
+            async update(params) {
+                await applyClaimedPolicy({ model: name, id: params.id }, params);
                 return commits.create({
-                    intent: mutationOptions?.intent,
-                    idempotencyKey: mutationOptions?.idempotencyKey,
-                    readAt: mutationOptions?.readAt,
-                    onStale: mutationOptions?.onStale,
-                    wait: mutationOptions?.wait,
+                    intent: params.intent,
+                    idempotencyKey: params.idempotencyKey,
+                    readAt: params.readAt,
+                    onStale: params.onStale,
+                    wait: params.wait,
                     operations: [
                         {
                             action: 'update',
                             model: name,
-                            id,
-                            data,
+                            id: params.id,
+                            data: params.data,
                         },
                     ],
                 });
             },
-            async delete(id, mutationOptions) {
-                await applyClaimedPolicy({ model: name, id }, mutationOptions);
+            async delete(params) {
+                await applyClaimedPolicy({ model: name, id: params.id }, params);
                 return commits.create({
-                    intent: mutationOptions?.intent,
-                    idempotencyKey: mutationOptions?.idempotencyKey,
-                    readAt: mutationOptions?.readAt,
-                    onStale: mutationOptions?.onStale,
-                    wait: mutationOptions?.wait,
+                    intent: params.intent,
+                    idempotencyKey: params.idempotencyKey,
+                    readAt: params.readAt,
+                    onStale: params.onStale,
+                    wait: params.wait,
                     operations: [
                         {
                             action: 'delete',
                             model: name,
-                            id,
+                            id: params.id,
                         },
                     ],
                 });
@@ -1384,6 +1483,83 @@ export function Ablo(options) {
         ...modelProxies,
         ready,
         waitForFlush,
+        setAuthToken(token) {
+            // The single credential source is read lazily by bootstrap HTTP,
+            // lazy query HTTP, network probes, and WebSocket reconnect URL auth.
+            // Updating it here is enough for the next request/connect to use the
+            // refreshed token; no per-transport patching.
+            authCredentials.setAuthToken(token);
+            // A fresh credential is useless to a connection parked in offline /
+            // backoff / auth_blocked until the next probe trigger — so kick one now.
+            // Harmless while connected (the FSM ignores the nudge there).
+            store.nudgeReconnect();
+        },
+        async getAuthToken() {
+            // The live short-lived bearer (set via `setAuthToken`/`getToken` refresh)
+            // is the canonical credential; fall back to a configured API key.
+            return (authCredentials.getAuthToken() ??
+                (await resolveApiKeyValue(configuredApiKey)) ??
+                configuredAuthToken ??
+                null);
+        },
+        setCredentialRefresher(refresher) {
+            store.setCredentialRefresher(refresher);
+        },
+        nudgeReconnect() {
+            store.nudgeReconnect();
+        },
+        sessions: {
+            // Stripe `ephemeralKeys.create` shape: a BACKEND (holding `sk_`) mints a
+            // short-lived scoped token for one end user OR one agent. Thin wrapper over
+            // the `/auth/capability` exchange, reshaped to a Stripe-style resource.
+            async create(params) {
+                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' });
+                }
+                const baseUrl = resolveBootstrapBaseUrl({
+                    url,
+                    bootstrapBaseUrl: internalOptions.bootstrapBaseUrl,
+                });
+                // Discriminate the union: `{ user }` → full-authority `ek_` (no op
+                // allowlist); `{ agent, can }` → scoped `rk_`. `can: { Task: ['update'] }`
+                // serializes to the wire allowlist `['task.update']` — the Hub matches
+                // `${model.toLowerCase()}.${op}` (Hub.ts handleCommit).
+                let participantKind;
+                let participantId;
+                let operations;
+                if (params.user) {
+                    participantKind = 'user';
+                    participantId = params.user.id;
+                    operations = undefined;
+                }
+                else {
+                    participantKind = 'agent';
+                    participantId = params.agent.id;
+                    operations = Object.entries(params.can).flatMap(([model, ops]) => (ops ?? []).map((op) => `${model.toLowerCase()}.${op}`));
+                }
+                const res = await exchangeApiKey({
+                    apiKey,
+                    baseUrl,
+                    participantKind,
+                    participantId,
+                    ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
+                    ...(operations ? { operations } : {}),
+                    ttlSeconds: params.ttlSeconds ?? 900,
+                    ...(params.userMeta ? { userMeta: params.userMeta } : {}),
+                    ...(internalOptions.fetch ? { fetch: internalOptions.fetch } : {}),
+                });
+                return {
+                    object: 'session',
+                    id: res.capabilityId,
+                    token: res.token,
+                    expiresAt: res.expiresAt,
+                    organizationId: res.organizationId,
+                    scope: res.scope,
+                    userMeta: res.userMeta,
+                };
+            },
+        },
         async dispose() {
             _refreshScheduler?.dispose();
             _refreshScheduler = null;
@@ -1476,10 +1652,7 @@ export function Ablo(options) {
         async beginTurn(beginOptions) {
             const baseUrl = url.replace(/\/+$/, '');
             const turnUrl = `${baseUrl.replace(/^ws/, 'http')}/api/agent/turn`;
-            const headers = { 'Content-Type': 'application/json' };
-            if (currentCapabilityToken) {
-                headers.Authorization = `Bearer ${currentCapabilityToken}`;
-            }
+            const headers = authCredentials.withAuthHeaders({ 'Content-Type': 'application/json' });
             const res = await fetch(turnUrl, {
                 method: 'POST',
                 headers,
@@ -1491,8 +1664,24 @@ export function Ablo(options) {
                 }),
             });
             if (!res.ok) {
-                const body = await res.text().catch(() => '<no body>');
-                throw new AbloError(`beginTurn failed: ${res.status} ${body}`, { code: 'turn_open_failed', httpStatus: res.status });
+                const text = await res.text().catch(() => '');
+                let parsed = text;
+                if (text) {
+                    try {
+                        parsed = JSON.parse(text);
+                    }
+                    catch {
+                        /* keep raw text */
+                    }
+                }
+                // Preserve the server's structured envelope (code/message/doc_url) when
+                // present; fall back to turn_open_failed for a bare/non-Ablo body.
+                throw hasWireCode(parsed)
+                    ? translateHttpError(res.status, parsed, res.headers.get('x-request-id') ?? undefined)
+                    : new AbloError(`beginTurn failed: ${res.status} ${text}`, {
+                        code: 'turn_open_failed',
+                        httpStatus: res.status,
+                    });
             }
             const json = (await res.json());
             const turnId = json.turnId;
@@ -1515,8 +1704,22 @@ export function Ablo(options) {
                     }),
                 });
                 if (!closeRes.ok) {
-                    const body = await closeRes.text().catch(() => '<no body>');
-                    throw new AbloError(`closeTurn failed: ${closeRes.status} ${body}`, { code: 'turn_close_failed', httpStatus: closeRes.status });
+                    const text = await closeRes.text().catch(() => '');
+                    let parsed = text;
+                    if (text) {
+                        try {
+                            parsed = JSON.parse(text);
+                        }
+                        catch {
+                            /* keep raw text */
+                        }
+                    }
+                    throw hasWireCode(parsed)
+                        ? translateHttpError(closeRes.status, parsed, closeRes.headers.get('x-request-id') ?? undefined)
+                        : new AbloError(`closeTurn failed: ${closeRes.status} ${text}`, {
+                            code: 'turn_close_failed',
+                            httpStatus: closeRes.status,
+                        });
                 }
             };
             const dispose = () => {

package/dist/client/ApiClient.d.ts

@@ -73,10 +73,42 @@ export interface CapabilityRevocation {
     readonly deleted: boolean;
     readonly activeSessionsClosed?: number;
 }
+export interface CapabilityRotateOptions {
+    /**
+     * Overlap window — the OLD token keeps authenticating for this long after
+     * rotation, so you can deploy the replacement with zero downtime. Default
+     * 24h server-side.
+     */
+    readonly grace?: Duration;
+    readonly graceSeconds?: number;
+    /**
+     * Lifetime of the REPLACEMENT capability. Omit to inherit the original's
+     * lifetime.
+     */
+    readonly lease?: Duration;
+    readonly leaseSeconds?: number;
+}
+/** The fresh capability returned by `rotate`, plus a pointer to the old one. */
+export interface RotatedCapability extends Capability {
+    /**
+     * The capability that was rotated out. Its token keeps working until
+     * `expiresAt` (the end of the grace window), then expires.
+     */
+    readonly rotatedFrom: {
+        readonly id: string;
+        readonly expiresAt: string;
+    };
+}
 export interface CapabilityResource {
     create(options: CapabilityCreateOptions): Promise<Capability>;
     retrieve(id: string): Promise<CapabilityRecord>;
     revoke(id: string): Promise<CapabilityRevocation>;
+    /**
+     * Rotate with overlap (Stripe's "roll" model): mint a fresh capability
+     * carrying the SAME scope, and keep the old token working for a grace
+     * window so you can roll out the replacement without downtime.
+     */
+    rotate(id: string, options?: CapabilityRotateOptions): Promise<RotatedCapability>;
     /**
      * Alias for `create`. Kept because "mint" is common capability-token
      * language, but `create` is the canonical SDK verb.
@@ -168,12 +200,20 @@ export interface AgentModelMutationOptions extends Omit<ModelMutationOptions, 'i
     } | null;
 }
 export interface AgentModelClient<T = Record<string, unknown>> {
-    retrieve(id: string, options?: AgentModelReadOptions): Promise<ModelRead<T>>;
-    create(data: Record<string, unknown>, options?: AgentModelMutationOptions & {
+    retrieve(params: AgentModelReadOptions & {
+        readonly id: string;
+    }): Promise<ModelRead<T>>;
+    create(params: AgentModelMutationOptions & {
+        readonly data: Record<string, unknown>;
         readonly id?: string | null;
     }): Promise<CommitReceipt>;
-    update(id: string, data: Record<string, unknown>, options?: AgentModelMutationOptions): Promise<CommitReceipt>;
-    delete(id: string, options?: AgentModelMutationOptions): Promise<CommitReceipt>;
+    update(params: AgentModelMutationOptions & {
+        readonly id: string;
+        readonly data: Record<string, unknown>;
+    }): Promise<CommitReceipt>;
+    delete(params: AgentModelMutationOptions & {
+        readonly id: string;
+    }): Promise<CommitReceipt>;
 }
 export interface AgentRunContext {
     readonly task: Task;
@@ -196,5 +236,13 @@ export interface AbloApi {
     agent(id: string, options: AgentOptions): Agent;
     model<T = Record<string, unknown>>(name: string): ModelClient<T>;
     beginTurn(options: TaskCreateOptions): Promise<Turn>;
+    /**
+     * Resolve the active bearer credential this client authenticates with — the
+     * same token its own requests carry in `Authorization`. Returns `null` when
+     * no credential is configured. Async because the API key may be supplied as
+     * an async setter. Use it to authenticate side-band requests to the same
+     * sync-server (e.g. the S3 presign endpoint) without re-minting.
+     */
+    getAuthToken(): Promise<string | null>;
 }
 export declare function createProtocolClient(options: AbloApiClientOptions): AbloApi;