@abloatai/ablo 0.25.0 → 0.27.0

package/dist/client/ApiClient.d.ts

@@ -1,29 +1,53 @@
 /**
- * Stateless API client for `Ablo({ apiKey })`.
- *
- * This is the hosted-API product surface: no schema, no object pool, no
- * IndexedDB, no WebSocket. It maps the public Model / Claim / Commit
- * nouns directly to HTTP routes on sync-server.
+ * The stateless API client behind `Ablo({ apiKey })`. It carries no schema,
+ * object pool, local database, or WebSocket, and maps the public Model, Claim,
+ * and Commit nouns directly to HTTP routes on the server. This is the transport
+ * used for server-side agents, workers, and serverless code.
  */
-import type { AbloOptions, CommitResource, ClaimCreateOptions, ClaimWaitOptions, ModelClient, ModelClaim, ModelTarget, CreateSessionParams, AbloSession } from './Ablo.js';
+import type { AbloOptions } from './options.js';
+import type { CommitResource, ClaimCreateOptions, ClaimWaitOptions, ModelClient, ModelClaim, ModelTarget, CreateSessionParams, AbloSession } from './resourceTypes.js';
 import type { SchemaRecord } from '../schema/schema.js';
 import type { Duration } from '../utils/duration.js';
-import type { Claim } from '../types/streams.js';
+import type { Claim, ClaimHeartbeat } from '../types/streams.js';
 import type { SyncObservabilityProvider } from '../interfaces/index.js';
 export type AbloApiClientOptions = Omit<AbloOptions, 'schema'> & {
     readonly schema?: null | undefined;
     readonly bootstrapBaseUrl?: string | undefined;
     /**
-     * Observability provider forwarded from `Ablo({ observability })`. The HTTP
-     * transport emits the same claim/conflict seams as the WS transport so a
-     * `ClaimLog` works identically for headless (server-agent) evals.
+     * The observability provider forwarded from `Ablo({ observability })`. The HTTP
+     * transport emits the same claim and conflict events as the WebSocket transport,
+     * so a `ClaimLog` works identically for headless server-agent evaluations.
      */
     readonly observability?: SyncObservabilityProvider;
+    /**
+     * Per-request deadline in milliseconds for the stateless HTTP transport.
+     * Every request this client issues is aborted after this long and surfaces
+     * as a retryable connection error — without it a black-holed server hangs
+     * a headless agent forever (browsers never time fetch out on their own).
+     * Pass `0` to disable the deadline.
+     *
+     * @default 30_000
+     */
+    readonly timeoutMs?: number;
 };
+/** Default per-request deadline for the stateless HTTP transport. */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 export interface AbloApiClaims {
     create(options: ClaimCreateOptions): Promise<Claim>;
     list(target?: Partial<ModelTarget>): Promise<readonly ModelClaim[]>;
     waitFor(target: Partial<ModelTarget>, options?: ClaimWaitOptions): Promise<void>;
+    /**
+     * The batched beat — extend every lease this credential holds in one
+     * request (`POST /v1/claims/heartbeat`), the stateless twin of the
+     * WebSocket keepalive. One round trip per cadence for a worker holding
+     * many rows. Returns one {@link ClaimHeartbeat} per extended lease,
+     * tagged with its claim id — no separate result type to learn.
+     */
+    heartbeatAll(options?: {
+        ttl?: Duration;
+    }): Promise<readonly (ClaimHeartbeat & {
+        readonly claimId: string;
+    })[]>;
 }
 export type CapabilityParticipantKind = 'agent' | 'system';
 export interface CapabilityCreateBaseOptions {
@@ -84,14 +108,14 @@ export interface CapabilityRevocation {
 }
 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.
+     * The overlap window — the old token keeps authenticating for this long after
+     * rotation, so you can deploy the replacement with zero downtime. Defaults to
+     * 24h on the server.
      */
     readonly grace?: Duration;
     readonly graceSeconds?: number;
     /**
-     * Lifetime of the REPLACEMENT capability. Omit to inherit the original's
+     * The lifetime of the replacement capability. Omit to inherit the original's
      * lifetime.
      */
     readonly lease?: Duration;
@@ -113,9 +137,9 @@ export interface CapabilityResource {
     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 with overlap: mint a fresh capability that carries 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>;
     /**
@@ -142,9 +166,9 @@ export interface AbloApi {
      */
     getAuthToken(): Promise<string | null>;
     /**
-     * Mint a short-lived scoped session — the Stripe `ephemeralKeys.create` shape.
-     * Minting is a control-plane HTTP call (no socket), so it lives on this stateless
-     * client too, not only the realtime one. `{ user }` → `ek_`, `{ agent, can }` → `rk_`.
+     * 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: {
         create(params: CreateSessionParams<SchemaRecord>): Promise<AbloSession>;

package/dist/client/ApiClient.js

@@ -1,17 +1,36 @@
 /**
- * Stateless API client for `Ablo({ apiKey })`.
- *
- * This is the hosted-API product surface: no schema, no object pool, no
- * IndexedDB, no WebSocket. It maps the public Model / Claim / Commit
- * nouns directly to HTTP routes on sync-server.
+ * The stateless API client behind `Ablo({ apiKey })`. It carries no schema,
+ * object pool, local database, or WebSocket, and maps the public Model, Claim,
+ * and Commit nouns directly to HTTP routes on the server. This is the transport
+ * used for server-side agents, workers, and serverless code.
  */
 import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, AbloNotFoundError, claimedError, translateHttpError, } from '../errors.js';
 import { reconcileFunctionalUpdate, } from './functionalUpdate.js';
 import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfCliKeyMismatch, warnIfDatabaseUrlEnvIgnored, warnIfDatabaseUrlDeprecated, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
-import { toSeconds } from '../utils/duration.js';
+import { PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER } from '../wire/protocolVersion.js';
+import { toMs, toSeconds } from '../utils/duration.js';
+import { heartbeatCadenceMs, resolveHeartbeatOptions, startClaimHeartbeatLoop, } from './claimHeartbeatLoop.js';
 import { mintSession } from './sessionMint.js';
+/**
+ * Interpret a heartbeat reply for a lease this handle HOLDS: anything other
+ * than `held` means the lease is no longer ours (a holder cannot be `queued`;
+ * `lost` rides a 409 that the wire error mapping already surfaces as
+ * AbloClaimedError before reaching here). The thrown loss is the definitive
+ * signal that stops the auto-heartbeat loop.
+ */
+function heldHeartbeatReply(reply, label) {
+    if (reply.status === 'held' && typeof reply.expiresAt === 'number') {
+        return {
+            expiresAt: reply.expiresAt,
+            ...(reply.queueDepth !== undefined ? { queueDepth: reply.queueDepth } : {}),
+        };
+    }
+    throw new AbloClaimedError(`The lease behind ${label} is no longer held — it expired or was granted onward. Re-acquire the claim and retry; a write attempted under the old lease is rejected by its \`readAt\` guard.`, { code: 'claim_lost' });
+}
 import { assertWriteOptions } from './writeOptionsSchema.js';
+/** Default per-request deadline for the stateless HTTP transport. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const DEFAULT_AGENT_LEASE = '10m';
 export function createProtocolClient(options) {
     const env = readProcessEnv();
@@ -29,11 +48,12 @@ export function createProtocolClient(options) {
         databaseUrl: configuredDatabaseUrl,
         dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
     });
-    // Observability seam for the STATELESS HTTP transport. The WS transport emits
-    // claim/conflict events from SyncWebSocket; the HTTP path (server-side agents,
+    // Observability hook for the stateless HTTP transport. The WebSocket transport
+    // emits claim and conflict events; the HTTP path (server-side agents,
     // `transport: 'http'`) emitted nothing, so a `ClaimLog` handed to a headless
-    // agent eval stayed empty. Mirror the two WS seams here: claim acquired +
-    // coordination-conflict rejection. No-op when no provider is configured.
+    // agent evaluation stayed empty. This mirrors the two WebSocket events here:
+    // claim acquired and coordination-conflict rejection. A no-op when no provider
+    // is configured.
     const observability = options.observability;
     // Shared by the two HTTP write doors (`commits.create` + per-model
     // `mutateModel`): a rejected write whose code is a coordination conflict is
@@ -101,6 +121,9 @@ export function createProtocolClient(options) {
         const headers = {
             'Content-Type': 'application/json',
             Authorization: `Bearer ${token}`,
+            // Protocol handshake for the HTTP transport (wire/protocolVersion.ts):
+            // the server answers an out-of-range version with a typed 426.
+            [PROTOCOL_VERSION_HEADER]: String(PROTOCOL_VERSION),
         };
         for (const [key, value] of Object.entries(options.defaultHeaders ?? {})) {
             if (value == null) {
@@ -120,20 +143,66 @@ export function createProtocolClient(options) {
         }
         return target.toString();
     }
+    const requestTimeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     async function requestJson(path, init) {
         await ready();
         const { idempotencyKey, ...requestInit } = init;
         const headers = await authHeaders();
         if (idempotencyKey)
             headers['Idempotency-Key'] = idempotencyKey;
-        const res = await fetchImpl(endpoint(path), {
-            ...requestInit,
-            headers: {
-                ...headers,
-                ...requestInit.headers,
-            },
-        });
-        const bodyText = await res.text();
+        // Deadline: abort the request after `timeoutMs` so a black-holed server
+        // can't hang the caller forever (fetch has NO default timeout in browsers,
+        // and only undici's generous defaults in Node). A caller-supplied signal
+        // is combined with the deadline via a shared controller — the portable
+        // equivalent of `AbortSignal.any([caller, AbortSignal.timeout(t)])`,
+        // which older runtimes (and the jsdom test env) don't implement. The
+        // same pattern already guards `query/client.ts` and `BootstrapFetcher`.
+        const callerSignal = requestInit.signal ?? undefined;
+        const controller = new AbortController();
+        const onCallerAbort = () => { controller.abort(callerSignal?.reason); };
+        if (callerSignal) {
+            if (callerSignal.aborted)
+                onCallerAbort();
+            else
+                callerSignal.addEventListener('abort', onCallerAbort, { once: true });
+        }
+        let timedOut = false;
+        const deadline = requestTimeoutMs > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                controller.abort();
+            }, requestTimeoutMs)
+            : null;
+        let res;
+        let bodyText;
+        try {
+            res = await fetchImpl(endpoint(path), {
+                ...requestInit,
+                signal: controller.signal,
+                headers: {
+                    ...headers,
+                    ...requestInit.headers,
+                },
+            });
+            // Keep the deadline armed while the body streams — a server that sends
+            // headers then stalls the body is the same hang with better manners.
+            bodyText = await res.text();
+        }
+        catch (error) {
+            if (timedOut) {
+                // Retryable by contract: `wait_for_timeout` is a registered transient
+                // transport code, so `isRetryableCode` steers callers to retry.
+                throw new AbloConnectionError(`The Ablo API did not respond within ${requestTimeoutMs}ms ` +
+                    `(${requestInit.method ?? 'GET'} ${path}). The request was aborted; ` +
+                    'it is safe to retry.', { code: 'wait_for_timeout', cause: error });
+            }
+            throw error;
+        }
+        finally {
+            if (deadline)
+                clearTimeout(deadline);
+            callerSignal?.removeEventListener('abort', onCallerAbort);
+        }
         const body = parseBody(bodyText);
         if (!res.ok) {
             throw translateHttpError(res.status, body ?? `Ablo API request failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
@@ -430,11 +499,11 @@ export function createProtocolClient(options) {
                     queue: claimOptions.queue,
                 }),
             });
-            // The fair-queue grant is PUSHED over a WebSocket (`claim_granted`),
-            // which this stateless HTTP client doesn't hold. Returning a handle here
-            // would be a phantom holder — a lease we can't confirm is ours. So a
-            // queued response is surfaced as a typed claimed signal; callers that need
-            // to *wait* in line use the realtime (WS-backed) `ablo.<model>.claim`.
+            // The fair-queue grant is pushed over a WebSocket (`claim_granted`), which
+            // this stateless HTTP client doesn't hold. Returning a handle here would be
+            // a phantom holder — a lease we can't confirm is ours. So a queued response
+            // is surfaced as a typed claimed signal; callers that need to wait in line
+            // use the realtime (WebSocket-backed) `ablo.<model>.claim`.
             if (body.status === 'queued') {
                 throw new AbloClaimedError(`Target ${claimOptions.target.model}/${claimOptions.target.id} is held; ` +
                     `queued at position ${body.position ?? 0}. The HTTP client can't await ` +
@@ -448,9 +517,24 @@ export function createProtocolClient(options) {
                 released = true;
                 await requestJson(`/v1/claims/${encodeURIComponent(id)}`, { method: 'DELETE' });
             };
+            // The by-id twin of the model-scoped heartbeat — same reply contract.
+            const heartbeat = async (beatOptions) => {
+                const resolved = resolveHeartbeatOptions(beatOptions);
+                const reply = await requestJson(`/v1/claims/${encodeURIComponent(id)}/heartbeat`, {
+                    method: 'POST',
+                    body: JSON.stringify({
+                        ...(resolved.ttl !== undefined ? { ttl: resolved.ttl } : {}),
+                        ...(resolved.details !== undefined
+                            ? { details: resolved.details }
+                            : {}),
+                    }),
+                });
+                return heldHeartbeatReply(reply, `claim ${id}`);
+            };
             return {
                 object: 'claim',
                 id,
+                heartbeat,
                 reason: claimOptions.reason,
                 target: {
                     type: claimOptions.target.model,
@@ -471,6 +555,23 @@ export function createProtocolClient(options) {
         waitFor(target, options) {
             return waitForNoClaims(target, options);
         },
+        async heartbeatAll(options) {
+            const reply = await requestJson('/v1/claims/heartbeat', {
+                method: 'POST',
+                body: JSON.stringify(options?.ttl !== undefined ? { ttl: options.ttl } : {}),
+            });
+            return (reply.results ?? []).flatMap((entry) => typeof entry.claimId === 'string' && typeof entry.expiresAt === 'number'
+                ? [
+                    {
+                        claimId: entry.claimId,
+                        expiresAt: entry.expiresAt,
+                        ...(entry.queueDepth !== undefined
+                            ? { queueDepth: entry.queueDepth }
+                            : {}),
+                    },
+                ]
+                : []);
+        },
     };
     async function listModel(modelName, options) {
         const params = new URLSearchParams();
@@ -502,11 +603,11 @@ export function createProtocolClient(options) {
         const query = await requestJson(`/v1/models/${encodeURIComponent(modelName)}/${encodeURIComponent(params.id)}`, {
             method: 'GET',
         });
-        // Miss = `data: undefined`, NOT a thrown error. The WebSocket client's
+        // A miss is `data: undefined`, not a thrown error. The WebSocket client's
         // `retrieve` returns `T | undefined` for a missing row; throwing only here
         // made the obvious read ("does this row exist?") a hard edge that an agent
-        // had to wrap in try/catch. Both transports now agree: absent row → absent
-        // data. Callers branch on `.data` (already the documented `.data?.x` usage).
+        // had to wrap in try/catch. Both transports agree: an absent row means absent
+        // data. Callers branch on `.data` (the documented `.data?.x` usage).
         // Normalize a miss to `undefined` (the server may send `null` or omit it).
         const data = (query.data ?? undefined);
         return {
@@ -516,16 +617,16 @@ export function createProtocolClient(options) {
         };
     }
     /**
-     * Single-op mutation over the model-scoped routes — the canonical surface
-     * that mirrors `ablo.<model>.create/update/delete`:
+     * A single-operation mutation over the model-scoped routes — the canonical
+     * surface that mirrors `ablo.<model>.create/update/delete`:
      *
      *   POST   /v1/models/:model        create
      *   PATCH  /v1/models/:model/:id     update
      *   DELETE /v1/models/:model/:id     delete
      *
-     * This replaces the previous indirection through `POST /v1/commits`. The raw
-     * `commits.create(...)` resource is still the path for ATOMIC MULTI-OP
-     * envelopes — this helper is the one-op, one-record path only.
+     * The `commits.create(...)` resource remains the path for atomic
+     * multi-operation envelopes; this helper handles the one-operation,
+     * one-record case.
      */
     async function mutateModel(action, modelName, id, data, options) {
         assertWriteOptions(options && {
@@ -569,9 +670,8 @@ export function createProtocolClient(options) {
             });
         }
         catch (error) {
-            // Per-model write door (`ablo.<model>.update/create/delete`) — the path
-            // the demo editor + server agents actually take. Capture coordination
-            // collisions here too; this single row IS the fallback target.
+            // The per-model write door (`ablo.<model>.update/create/delete`). Capture
+            // coordination collisions here too; this single row is the fallback target.
             recordCoordinationConflict(error, clientTxId, [{ model: modelName, id }]);
             throw error;
         }
@@ -617,9 +717,25 @@ export function createProtocolClient(options) {
                 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: 'claim_queued' });
             }
-            return body.claim?.id ?? body.id ?? body.id ?? createClaimId();
+            // `claimId` is the field name the queued response uses; check it alongside
+            // the other id shapes the response may carry.
+            return body.claim?.id ?? body.id ?? body.claimId ?? createClaimId();
         };
         const releaseClaim = (params) => requestJson(claimPath(isClaimHandle(params) ? params.target.id : params.id), { method: 'DELETE' }).then(() => undefined);
+        // One beat on the held lease. A lapsed lease answers `claim_lost`
+        // (409), which the wire error mapping surfaces as AbloClaimedError —
+        // the definitive signal that stops the auto-heartbeat loop.
+        const heartbeatClaim = async (id, claimId, options) => {
+            const reply = await requestJson(`${claimPath(id)}/heartbeat`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    claimId,
+                    ...(options.ttl !== undefined ? { ttl: options.ttl } : {}),
+                    ...(options.details !== undefined ? { details: options.details } : {}),
+                }),
+            });
+            return heldHeartbeatReply(reply, `claim ${claimId} on ${name}/${id}`);
+        };
         async function claimImpl(params) {
             const claimId = await acquireClaim(params);
             observability?.captureClaim({
@@ -637,7 +753,33 @@ export function createProtocolClient(options) {
             if (data === undefined) {
                 throw new AbloNotFoundError(`Cannot claim ${name}/${params.id}: it does not exist (or is outside this credential's scope).`, [params.id]);
             }
-            const release = () => releaseClaim(params);
+            const heartbeat = async (beatOptions) => {
+                const resolved = resolveHeartbeatOptions(beatOptions);
+                const beat = await heartbeatClaim(params.id, claimId, {
+                    ttl: resolved.ttl ?? params.ttl,
+                    ...(resolved.details !== undefined
+                        ? { details: resolved.details }
+                        : {}),
+                });
+                params.onHeartbeat?.(beat);
+                return beat;
+            };
+            // Opt-in auto-heartbeat — the background-worker cadence. The stateless
+            // HTTP claim defaults to the server's 60s acquire window when no TTL
+            // was requested, so the default cadence lands at 20s beats.
+            const stopHeartbeatLoop = params.heartbeat
+                ? startClaimHeartbeatLoop({
+                    beat: () => heartbeat(),
+                    intervalMs: heartbeatCadenceMs(params.ttl !== undefined ? toMs(params.ttl) : 60_000, params.heartbeat),
+                    ...(params.onHeartbeatLost
+                        ? { onLost: params.onHeartbeatLost }
+                        : {}),
+                })
+                : undefined;
+            const release = () => {
+                stopHeartbeatLoop?.();
+                return releaseClaim(params);
+            };
             return {
                 object: 'claim',
                 id: claimId,
@@ -657,6 +799,7 @@ export function createProtocolClient(options) {
                 revoke: () => {
                     void release().catch(() => { });
                 },
+                heartbeat,
                 [Symbol.asyncDispose]: release,
             };
         }
@@ -675,8 +818,8 @@ export function createProtocolClient(options) {
             reorder: async (params) => {
                 await requestJson(`${claimPath(params.id)}/reorder`, {
                     method: 'POST',
-                    // The reorder route's payload is `{ heldBy, claimId }[]` — Claim's id
-                    // IS the claimId.
+                    // The reorder route's payload is `{ heldBy, claimId }[]` — a Claim's id
+                    // is the claimId.
                     body: JSON.stringify({ order: params.order.map((i) => ({ heldBy: i.heldBy, claimId: i.id })) }),
                 });
             },
@@ -688,7 +831,13 @@ export function createProtocolClient(options) {
             if (isClaimHandle(claimInput)) {
                 return run({ ...input, claimRef: { id: claimInput.id }, claim: undefined });
             }
-            const claimId = await acquireClaim({ id, ...claimInput });
+            // `isClaimHandle` ruled out the handle form above; the generic mismatch
+            // (the union carries `Claim`, the guard narrows `Claim<T>`) keeps the
+            // compiler from subtracting it, so narrow to the inline-options form.
+            const claimId = await acquireClaim({
+                id,
+                ...claimInput,
+            });
             try {
                 return await run({ ...input, claimRef: { id: claimId }, claim: undefined });
             }
@@ -742,8 +891,8 @@ export function createProtocolClient(options) {
                     // Confirm the write, then return the row — the obvious expectation of
                     // "create" (the WebSocket client already returns the row). The read-
                     // back is the authoritative server row, so it carries the framework
-                    // defaults (createdAt/createdBy/…) AND, for an idempotent re-create of
-                    // an existing id, the EXISTING row rather than the caller's input.
+                    // defaults (createdAt, createdBy, …) and, for an idempotent re-create of
+                    // an existing id, the existing row rather than the caller's input.
                     await mutateModel('create', name, id, params.data, {
                         ...options,
                         wait: options?.wait ?? 'confirmed',
@@ -775,9 +924,9 @@ export function createProtocolClient(options) {
         model,
         sessions: {
             async create(params) {
-                // Stateless mint: the configured key IS the control-plane credential here
-                // (no startup `rk_` exchange runs on this client). Reuse the resolved base
-                // URL + fetch; the shared `mintSession` owns the two server doors.
+                // 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' });