@abloatai/ablo 0.20.2 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.21.0
+
+### Minor Changes
+
+- Coordination observability now fires on BOTH transports. Previously `captureClaim`/`captureConflict` were emitted only by the WebSocket transport, so a `ClaimLog` (or any `observability` provider) handed to a stateless HTTP client — the transport server-side agents use via `Ablo({ transport: 'http' })` — stayed empty, and even on WebSocket a hard commit rejection went unrecorded. Fixed:
+  - **HTTP transport now emits.** `Ablo({ transport: 'http', observability })` records `claim` acquisition (`captureClaim`) and coordination-conflict rejections (`captureConflict`, code `stale_context` / `claim_conflict` / `entity_claimed`) on BOTH HTTP write doors (`commits.create` and per-model `ablo.<model>.update/create/delete`). The conflict names the collided rows — from the server's `conflicts` detail when present, otherwise the ops the write attempted. `observability` is now a documented option on the HTTP client.
+  - **WebSocket rejections now recorded.** A commit rejected by the conflict policy (`mutation_result` `success: false` with a coordination code) now calls `captureConflict`, mirroring the existing notify-on-success path. So `ClaimLog.collisions()` no longer silently misses rejected writes.
+
+  Net effect: a `ClaimLog` behaves identically regardless of transport — `entries`, `collisions()`, and `onChange` reflect the real coordination timeline for headless agent evals and live activity feeds alike.
+
 ## 0.20.2
 
 ### Patch Changes

package/dist/client/ApiClient.d.ts

@@ -9,9 +9,16 @@ import type { AbloOptions, CommitResource, ClaimCreateOptions, ClaimWaitOptions,
 import type { SchemaRecord } from '../schema/schema.js';
 import type { Duration } from '../utils/duration.js';
 import type { Claim } 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.
+     */
+    readonly observability?: SyncObservabilityProvider;
 };
 export interface AbloApiClaims {
     create(options: ClaimCreateOptions): Promise<Claim>;

package/dist/client/ApiClient.js

@@ -28,6 +28,38 @@ 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,
+    // `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.
+    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
+    // the collision ClaimLog exists to surface. Prefer the server's `conflicts`
+    // detail (carried on the typed error / envelope); fall back to the rows the
+    // caller tried to write so the collision always names a target. Inert without
+    // a provider or for non-conflict errors. Never throws (capture is best-effort).
+    const recordCoordinationConflict = (error, clientTxId, fallbackRows) => {
+        if (!observability)
+            return;
+        const code = error?.code;
+        const isConflict = code === 'stale_context' ||
+            code === 'claim_conflict' ||
+            code === 'entity_claimed' ||
+            (typeof code === 'string' && code.startsWith('policy:'));
+        if (!isConflict)
+            return;
+        const rawConflicts = error?.conflicts;
+        const rows = Array.isArray(rawConflicts) && rawConflicts.length > 0
+            ? rawConflicts.map((r) => ({
+                model: typeof r.model === 'string' ? r.model : 'unknown',
+                id: typeof r.id === 'string' ? r.id : 'unknown',
+                fields: [],
+            }))
+            : fallbackRows.map((r) => ({ model: r.model, id: r.id, fields: [] }));
+        observability.captureConflict({ clientTxId, rows });
+    };
     const fetchImpl = options.fetch ?? globalThis.fetch;
     if (typeof fetchImpl !== 'function') {
         throw new AbloConnectionError('Ablo API client requires a fetch implementation. Pass `fetch` in Ablo({ ... }) for this runtime.', { code: 'fetch_unavailable' });
@@ -256,16 +288,29 @@ export function createProtocolClient(options) {
                 readAt: commitOptions.readAt ?? claim?.readAt ?? null,
                 onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
             });
-            const body = await requestJson('/v1/commits', {
-                method: 'POST',
-                idempotencyKey: clientTxId,
-                body: JSON.stringify({
-                    clientTxId,
+            let body;
+            try {
+                body = await requestJson('/v1/commits', {
+                    method: 'POST',
                     idempotencyKey: clientTxId,
-                    claim: normalizeClaimId(commitOptions.claimRef) ?? claim?.id,
-                    operations,
-                }),
-            });
+                    body: JSON.stringify({
+                        clientTxId,
+                        idempotencyKey: clientTxId,
+                        claim: normalizeClaimId(commitOptions.claimRef) ?? claim?.id,
+                        operations,
+                    }),
+                });
+            }
+            catch (error) {
+                // Coordination collision over HTTP — surface it to observability on the
+                // same footing as the WS transport, then rethrow unchanged. Fall back to
+                // the ops we tried to write so the collision always names a row.
+                recordCoordinationConflict(error, clientTxId, operations.map((o) => ({
+                    model: typeof o.model === 'string' ? o.model : 'unknown',
+                    id: typeof o.id === 'string' ? o.id : 'unknown',
+                })));
+                throw error;
+            }
             // `requestJson` throws via `translateHttpError` on any non-2xx,
             // so reaching here implies success. Narrow `status` to the
             // `CommitWait`-compatible subset; `'rejected'` only appears on
@@ -511,11 +556,21 @@ export function createProtocolClient(options) {
             requestBody.id = id;
         if (data !== undefined)
             requestBody.data = data;
-        const body = await requestJson(path, {
-            method,
-            idempotencyKey: clientTxId,
-            body: JSON.stringify(requestBody),
-        });
+        let body;
+        try {
+            body = await requestJson(path, {
+                method,
+                idempotencyKey: clientTxId,
+                body: JSON.stringify(requestBody),
+            });
+        }
+        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.
+            recordCoordinationConflict(error, clientTxId, [{ model: modelName, id }]);
+            throw error;
+        }
         // `requestJson` throws via `translateHttpError` on any non-2xx, so reaching
         // here implies success. Narrow `status` to the `CommitWait`-compatible
         // subset; `'rejected'` only appears on a thrown rejection body.
@@ -563,6 +618,14 @@ export function createProtocolClient(options) {
         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);
+            observability?.captureClaim({
+                phase: 'acquired',
+                claimId,
+                model: name,
+                id: params.id,
+                ...(params.field ? { field: params.field } : {}),
+                reason: params.reason ?? 'editing',
+            });
             const { data, stamp } = await retrieveModel(name, { id: params.id });
             const release = () => releaseClaim(params);
             return {

package/dist/client/auth.js

@@ -96,7 +96,13 @@ function activeProjectSlug(value) {
     return typeof slug === 'string' && slug.length > 0 ? slug : undefined;
 }
 function importNodeBuiltin(specifier) {
-    return import(specifier);
+    // Node-only runtime import (CLI credential snapshot). The call is dead in
+    // browser/edge builds — guarded by `process.versions.node` and `window`
+    // checks in the callers — but bundlers still try to resolve the dynamic
+    // `import()` and Turbopack fails the build on the unanalyzable specifier.
+    // The magic comments tell each bundler to emit the import verbatim and never
+    // resolve it. Keep both so webpack and Turbopack consumers are covered.
+    return import(/* webpackIgnore: true */ /* turbopackIgnore: true */ specifier);
 }
 async function readJsonIfPresent(path) {
     try {

package/dist/sync/SyncWebSocket.js

@@ -404,6 +404,36 @@ export class SyncWebSocket extends EventEmitter {
                             else {
                                 errorMessage = 'mutation failed on server';
                             }
+                            // Coordination collision: a stale-context rejection (the write's
+                            // readAt premise moved underneath) or a foreign-claim conflict is
+                            // exactly the collision ClaimLog exists to surface. The notify
+                            // path (success + notifications) emits captureConflict above; a
+                            // HARD rejection must too — otherwise observability.collisions()
+                            // silently misses every rejected write. The conflicted rows ride
+                            // along on the typed error's `conflicts` detail (see
+                            // AbloStaleContextError.toJSON / errorEnvelope).
+                            if (errorCode === 'stale_context' ||
+                                errorCode === 'claim_conflict' ||
+                                errorCode === 'entity_claimed' ||
+                                errorCode?.startsWith('policy:') === true) {
+                                const rawConflicts = error != null &&
+                                    typeof error === 'object' &&
+                                    Array.isArray(error.conflicts)
+                                    ? error
+                                        .conflicts
+                                    : [];
+                                const conflictEvent = {
+                                    clientTxId: typeof clientTxId === 'string' ? clientTxId : '',
+                                    rows: rawConflicts.map((r) => ({
+                                        model: typeof r.model === 'string' ? r.model : 'unknown',
+                                        id: typeof r.id === 'string' ? r.id : 'unknown',
+                                        fields: [],
+                                    })),
+                                };
+                                const ctx = getContext();
+                                ctx.observability.breadcrumb(formatConflict(conflictEvent), 'sync.coordination', 'warning');
+                                ctx.observability.captureConflict(conflictEvent);
+                            }
                             // Build the proper typed AbloError from the wire code via the
                             // shared factory — the same code→class mapping the HTTP commit
                             // path uses (`translateHttpError`). This keeps rejected commits

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.20.2",
+  "version": "0.21.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",