@abloatai/ablo 0.8.0 → 0.9.0

package/dist/client/Ablo.js

@@ -11,9 +11,12 @@
  *   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, AbloAuthenticationError, AbloConnectionError, AbloValidationError, translateHttpError, hasWireCode, toAbloError } from '../errors.js';
@@ -23,6 +26,7 @@ import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, no
 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';
@@ -646,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);
@@ -655,6 +690,12 @@ 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,
@@ -724,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 →
@@ -742,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
@@ -812,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;
@@ -831,6 +875,20 @@ 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
@@ -856,20 +914,15 @@ export function Ablo(options) {
                     // 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 `currentCapabilityToken`. Reading the frozen
+                    // `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 `authHeaders()`'s `currentCapabilityToken ??
-                    // configuredAuthToken` precedence.
-                    configuredAuthToken: currentCapabilityToken ?? configuredAuthToken,
+                    // 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
@@ -895,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;
                 }
@@ -962,6 +1013,16 @@ export function Ablo(options) {
                     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;
             }
         })();
@@ -992,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)
@@ -1048,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,
@@ -1072,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,
@@ -1320,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: [
                     {
@@ -1362,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,
                         },
                     ],
                 });
@@ -1426,14 +1484,29 @@ export function Ablo(options) {
         ready,
         waitForFlush,
         setAuthToken(token) {
-            // Same rotation path as the internal capability-token refresh
-            // (`applyRotatedToken` in `ready()`): update the closure binding the
-            // HTTP hydration provider reads, push to the bootstrap helper's header,
-            // and swap it on the live WebSocket. Decoupled from `ready()` so a
-            // refreshed JWT can be pushed at any point in the engine's lifetime.
-            currentCapabilityToken = token;
-            bootstrapHelper.setAuthToken(token);
-            store.getSyncWebSocket()?.setCapabilityToken(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
@@ -1579,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,

package/dist/client/ApiClient.d.ts

@@ -200,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;
@@ -228,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;

package/dist/client/ApiClient.js

@@ -171,32 +171,36 @@ export function createProtocolClient(options) {
     function createAgentModelClient(agentClient, name) {
         const base = agentClient.model(name);
         return {
-            retrieve(id, options) {
+            retrieve(params) {
                 // Reads are never blocked by a claim (coordination.md): a claim
                 // serializes WRITERS, not readers. So — unlike the create/update/
                 // delete paths below — retrieve does NOT apply the agent claimed
                 // default; options pass through and the read path's `'return'`
                 // default keeps a claimed row readable. A caller can still opt into
                 // gating with an explicit `ifClaimed` (developer's choice).
-                return base.retrieve(id, options);
+                return base.retrieve(params);
             },
-            create(data, mutationOptions) {
-                const id = mutationOptions?.id ?? createModelId();
-                return withAgentIntent(agentClient, name, id, mutationOptions, (commitIntent) => base.create(data, {
-                    ...stripAgentRuntimeOptions(mutationOptions),
+            create(params) {
+                const id = params.id ?? createModelId();
+                return withAgentIntent(agentClient, name, id, params, (commitIntent) => base.create({
+                    ...stripAgentRuntimeOptions(params),
                     id,
+                    data: params.data,
                     intent: commitIntent,
                 }));
             },
-            update(id, data, mutationOptions) {
-                return withAgentIntent(agentClient, name, id, mutationOptions, (commitIntent) => base.update(id, data, {
-                    ...stripAgentRuntimeOptions(mutationOptions),
+            update(params) {
+                return withAgentIntent(agentClient, name, params.id, params, (commitIntent) => base.update({
+                    ...stripAgentRuntimeOptions(params),
+                    id: params.id,
+                    data: params.data,
                     intent: commitIntent,
                 }));
             },
-            delete(id, mutationOptions) {
-                return withAgentIntent(agentClient, name, id, mutationOptions, (commitIntent) => base.delete(id, {
-                    ...stripAgentRuntimeOptions(mutationOptions),
+            delete(params) {
+                return withAgentIntent(agentClient, name, params.id, params, (commitIntent) => base.delete({
+                    ...stripAgentRuntimeOptions(params),
+                    id: params.id,
                     intent: commitIntent,
                 }));
             },
@@ -562,14 +566,39 @@ export function createProtocolClient(options) {
             return waitForNoIntents(target, options);
         },
     };
-    async function retrieveModel(modelName, id, options) {
-        await applyClaimedPolicy({ model: modelName, id }, options);
-        const query = await requestJson(`/v1/models/${encodeURIComponent(modelName)}/${encodeURIComponent(id)}`, {
+    async function listModel(modelName, options) {
+        const params = new URLSearchParams();
+        if (options?.limit !== undefined)
+            params.set('limit', String(options.limit));
+        if (options?.orderBy) {
+            const [col, dir] = Object.entries(options.orderBy)[0] ?? [];
+            if (col) {
+                params.set('order_by', col);
+                if (dir === 'desc')
+                    params.set('order', 'desc');
+            }
+        }
+        // The collection route turns any non-reserved query param into an equality
+        // filter (`?status=todo`). The wire is AND-only equality — matches what a
+        // stateless reactor needs; richer predicates stay on the stateful path.
+        if (options?.where && typeof options.where === 'object') {
+            for (const [k, v] of Object.entries(options.where)) {
+                if (v !== undefined && v !== null && typeof v !== 'object')
+                    params.set(k, String(v));
+            }
+        }
+        const qs = params.toString();
+        const res = await requestJson(`/v1/models/${encodeURIComponent(modelName)}${qs ? `?${qs}` : ''}`, { method: 'GET' });
+        return res.data ?? [];
+    }
+    async function retrieveModel(modelName, params) {
+        await applyClaimedPolicy({ model: modelName, id: params.id }, params);
+        const query = await requestJson(`/v1/models/${encodeURIComponent(modelName)}/${encodeURIComponent(params.id)}`, {
             method: 'GET',
         });
         const data = query.data;
         if (!data) {
-            throw new AbloValidationError(`Model row not found: ${modelName}/${id}`, { code: 'model_not_found' });
+            throw new AbloValidationError(`Model row not found: ${modelName}/${params.id}`, { code: 'model_not_found' });
         }
         return {
             data,
@@ -622,22 +651,126 @@ export function createProtocolClient(options) {
         };
     }
     function model(name) {
+        // Durable lease + FIFO wait-line over HTTP (the existing claim routes). A
+        // claim is server state, not a subscription — acquire/hold/release are plain
+        // request/response, so a stateless agent participates in coordination too.
+        const claimPath = (id) => `/v1/models/${encodeURIComponent(name)}/${encodeURIComponent(id)}/claim`;
+        const isClaimHandle = (value) => typeof value === 'object' &&
+            value !== null &&
+            value.object === 'claim' &&
+            typeof value.claimId === 'string' &&
+            typeof value.release === 'function';
+        const claimMeta = (options) => {
+            if (!options?.description)
+                return options?.meta;
+            return { ...(options.meta ?? {}), description: options.description };
+        };
+        const acquireClaim = async (params) => {
+            const body = await requestJson(claimPath(params.id), {
+                method: 'POST',
+                body: JSON.stringify({
+                    action: params.action ?? 'editing',
+                    ...(params.ttl !== undefined ? { ttl: params.ttl } : {}),
+                    ...(params.description !== undefined ? { description: params.description } : {}),
+                    ...(claimMeta(params) ? { meta: claimMeta(params) } : {}),
+                    // `wait` (default true) → queue behind the holder; false → fail-fast
+                    // with AbloClaimedError (work-distribution dedup).
+                    queue: params.wait ?? true,
+                }),
+            });
+            if (body.status === 'queued') {
+                throw new AbloClaimedError(`Target ${name}/${params.id} is held; queued at position ${body.position ?? 0}. ` +
+                    `The HTTP client cannot await the grant without a WebSocket.`, { code: 'intent_queued' });
+            }
+            return body.intent?.id ?? body.id ?? body.intentId ?? createIntentId();
+        };
+        const releaseClaim = (params) => requestJson(claimPath(isClaimHandle(params) ? params.target.id : params.id), { method: 'DELETE' }).then(() => undefined);
+        async function claimImpl(params) {
+            const claimId = await acquireClaim(params);
+            const { data } = await retrieveModel(name, { id: params.id });
+            const release = () => releaseClaim(params);
+            return {
+                object: 'claim',
+                claimId,
+                target: {
+                    model: name,
+                    id: params.id,
+                    ...(params.field ? { field: params.field } : {}),
+                    ...(params.path ? { path: params.path } : {}),
+                    ...(params.range ? { range: params.range } : {}),
+                    ...(claimMeta(params) ? { meta: claimMeta(params) } : {}),
+                },
+                action: params.action ?? 'editing',
+                ...(params.description ? { description: params.description } : {}),
+                data,
+                release,
+                revoke: () => {
+                    void release().catch(() => { });
+                },
+                [Symbol.asyncDispose]: release,
+            };
+        }
+        const intentsForEntity = async (params) => requestJson(`/v1/intents?model=${encodeURIComponent(name)}&id=${encodeURIComponent(params.id)}${params.field ? `&field=${encodeURIComponent(params.field)}` : ''}`, { method: 'GET' });
+        const claim = Object.assign(claimImpl, {
+            release: releaseClaim,
+            state: async (params) => {
+                const res = await intentsForEntity(params);
+                return res.intents?.[0] ?? null;
+            },
+            queue: async (params) => {
+                const res = await intentsForEntity(params);
+                return { object: 'list', data: res.queue ?? [] };
+            },
+            reorder: async (params) => {
+                await requestJson(`${claimPath(params.id)}/reorder`, {
+                    method: 'POST',
+                    // The reorder route's payload is `{ heldBy, intentId }[]` — Intent's id
+                    // IS the intentId.
+                    body: JSON.stringify({ order: params.order.map((i) => ({ heldBy: i.heldBy, intentId: i.id })) }),
+                });
+            },
+        });
+        const withMutationClaim = async (id, input, run) => {
+            const claimInput = input?.claim;
+            if (!claimInput)
+                return run(input);
+            if (isClaimHandle(claimInput)) {
+                return run({ ...input, intent: { id: claimInput.claimId }, claim: undefined });
+            }
+            const claimId = await acquireClaim({ id, ...claimInput });
+            try {
+                return await run({ ...input, intent: { id: claimId }, claim: undefined });
+            }
+            finally {
+                await releaseClaim({ id }).catch(() => { });
+            }
+        };
         return {
-            retrieve(id, options) {
-                return retrieveModel(name, id, options);
+            claim,
+            retrieve(params) {
+                return retrieveModel(name, params);
             },
-            async create(data, mutationOptions) {
-                const id = mutationOptions?.id ?? createModelId();
-                await applyClaimedPolicy({ model: name, id }, mutationOptions);
-                return mutateModel('create', name, id, data, mutationOptions);
+            list(options) {
+                return listModel(name, options);
             },
-            async update(id, data, mutationOptions) {
-                await applyClaimedPolicy({ model: name, id }, mutationOptions);
-                return mutateModel('update', name, id, data, mutationOptions);
+            async create(params) {
+                const id = params.id ?? createModelId();
+                return withMutationClaim(id, params, async (options) => {
+                    await applyClaimedPolicy({ model: name, id }, options);
+                    return mutateModel('create', name, id, params.data, options);
+                });
             },
-            async delete(id, mutationOptions) {
-                await applyClaimedPolicy({ model: name, id }, mutationOptions);
-                return mutateModel('delete', name, id, undefined, mutationOptions);
+            async update(params) {
+                return withMutationClaim(params.id, params, async (options) => {
+                    await applyClaimedPolicy({ model: name, id: params.id }, options);
+                    return mutateModel('update', name, params.id, params.data, options);
+                });
+            },
+            async delete(params) {
+                return withMutationClaim(params.id, params, async (options) => {
+                    await applyClaimedPolicy({ model: name, id: params.id }, options);
+                    return mutateModel('delete', name, params.id, undefined, options);
+                });
             },
         };
     }
@@ -652,6 +785,11 @@ export function createProtocolClient(options) {
         commits,
         model,
         agent: createAgent,
+        async getAuthToken() {
+            // 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;
+        },
         async beginTurn(turnOptions) {
             const task = await tasks.create(turnOptions);
             let closed = false;