@abloatai/ablo 0.22.1 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 0.24.0
+
+### Minor Changes
+
+- Multi-agent coordination for AI SDK tools + safer `ablo push`.
+  - **`coordinatedTool` (`@abloatai/ablo/ai-sdk`)** — one call turns an Ablo model
+    write into a Vercel AI SDK `tool()` with concurrency coordination handled, so an
+    AI agent can contribute to shared state without clobbering concurrent writers.
+    Three strategies: `merge` (default — delegates to the functional update's
+    compare-and-swap + backoff, self-healing accumulate), `claim` (mutual exclusion,
+    returns a `claimed` signal the model retries on), and `queue` (SQS-style
+    poll-acquire over HTTP). The `ai-sdk` entry now also documents the canonical
+    multi-agent coordination model (surface-the-signal + back-off laws, strategy
+    table).
+  - **`ablo push` guards** — `--dry-run`/`--plan` prints the deploy target, a
+    model-level diff vs the deployed schema, and git state, then exits without
+    applying. Production deploys now require a typed confirmation (and refuse an
+    uncommitted schema unless `--allow-dirty`); sandbox confirms interactively.
+    `--yes`/`-y` skips confirmation for CI.
+
+## 0.23.0
+
+### Minor Changes
+
+- 2807efb: `create` now returns the created row, not a `CommitReceipt`.
+
+  The WebSocket client's `create` already returned the row (`T`); the HTTP client
+  and the `.model(name)` accessor returned a `CommitReceipt`, so "create returns
+  the thing I created" only held on one transport. Both now return the confirmed,
+  authoritative server row (framework defaults like `createdAt`/`createdBy`
+  included). For an idempotent re-create of an existing caller-supplied id, the
+  EXISTING row is returned (not the input).
+
+  BREAKING (HTTP / `.model()` callers only): `await ablo.<model>.create(...)` now
+  resolves to the row instead of `{ status, lastSyncId, ... }`. Code that ignored
+  the return value, or that read `.id` (the row carries `id` too), is unaffected;
+  code that read `lastSyncId` / `serverTxId` / `status` off a typed model create
+  should use the raw `commits.create(...)` resource, which still returns a
+  `CommitReceipt`. WebSocket-client callers are unaffected (already returned `T`).
+
+- 2807efb: `delete` is idempotent — deleting an already-absent row is a no-op success, not
+  an error.
+
+  The WebSocket client's `delete` threw `entity_not_found` when the row wasn't in
+  the local pool, while the HTTP client returned without error — so "delete this"
+  was a hard edge on one transport. Both now agree: a row that isn't present is
+  already gone, so the delete succeeds with no effect. This is AIP-135's
+  recommended behavior for client-assigned-id / declarative APIs (Ablo is exactly
+  that), and it makes delete safe to retry and to race (two actors deleting the
+  same row). The deliberate "loud 0-row" assertion in `@ablo/slides-sdk` is
+  unchanged (it keeps its own `allowMissing` opt-out).
+
+- 2807efb: `retrieve` reports a missing row as `data: undefined` instead of throwing.
+
+  The HTTP client previously threw `model_not_found` for a missing row while the
+  WebSocket client returned `T | undefined` — so the obvious read ("does this row
+  exist?") was a hard edge an agent had to wrap in `try/catch` on one transport
+  only. Both transports now agree: an absent row is data-absence, not an error.
+  `ModelRead.data` is now `T | undefined` (matching the documented `.data?.x`
+  usage). Taking a `claim` on a row that doesn't exist still throws
+  `AbloNotFoundError` — a claim has nothing to hold.
+
 ## 0.22.1
 
 ### Patch Changes

package/dist/BaseSyncedStore.js

@@ -215,7 +215,7 @@ export class BaseSyncedStore {
                     this.hydratedGroups.add(g);
             }
             catch (err) {
-                getContext().logger.warn('[BaseSyncedStore] scoped hydrate failed', {
+                getContext().logger.debug('[BaseSyncedStore] scoped hydrate failed', {
                     syncGroups: need,
                     error: err instanceof Error ? err.message : String(err),
                 });
@@ -684,7 +684,7 @@ export class BaseSyncedStore {
                     }
                 }
                 catch (fallbackError) {
-                    getContext().logger.warn('[BaseSyncedStore] Local fallback failed', {
+                    getContext().logger.debug('[BaseSyncedStore] Local fallback failed', {
                         error: fallbackError.message,
                     });
                 }
@@ -752,7 +752,7 @@ export class BaseSyncedStore {
                         "(e.g. new URL('/api/ablo-session', process.env.NEXT_PUBLIC_APP_URL)).", { error: message });
                 }
                 else {
-                    getContext().logger.warn('access-credential re-mint failed (transient)', { error: message });
+                    getContext().logger.debug('access-credential re-mint failed (transient)', { error: message });
                 }
                 return 'network_error';
             }
@@ -951,7 +951,7 @@ export class BaseSyncedStore {
         const rawObj = (raw ?? {});
         const groupKey = typeof rawObj.group === 'string' ? rawObj.group : undefined;
         if (!groupKey) {
-            getContext().logger.warn('[BaseSyncedStore] Group removed delta missing group key', {
+            getContext().logger.debug('[BaseSyncedStore] Group removed delta missing group key', {
                 syncId: delta.id,
             });
             return;
@@ -1040,7 +1040,7 @@ export class BaseSyncedStore {
             });
         }
         catch (error) {
-            getContext().logger.warn('[BaseSyncedStore] Failed to check sync group shrinkage', {
+            getContext().logger.debug('[BaseSyncedStore] Failed to check sync group shrinkage', {
                 error: error instanceof Error ? error.message : String(error),
             });
         }
@@ -1102,7 +1102,7 @@ export class BaseSyncedStore {
                 hasLocalData = this.objectPool.size > 0;
             }
             catch (hydrateError) {
-                getContext().logger.warn('[sync-engine] IDB hydration failed', { error: hydrateError });
+                getContext().logger.debug('[sync-engine] IDB hydration failed', { error: hydrateError });
                 getContext().observability.captureBootstrapFailure(hydrateError, { type: 'hydration-from-idb' });
             }
             // Get sync baseline for WebSocket
@@ -1221,7 +1221,7 @@ export class BaseSyncedStore {
                 this.updateSyncStatus({ state: 'idle', progress: 100 });
             }
             catch (error) {
-                getContext().logger.warn('[sync-engine] Background bootstrap failed', {
+                getContext().logger.debug('[sync-engine] Background bootstrap failed', {
                     error: error instanceof Error ? error.message : String(error),
                     cause: error,
                 });
@@ -1418,7 +1418,7 @@ export class BaseSyncedStore {
                     return;
                 resolved = true;
                 unsubscribe();
-                getContext().logger.warn(`[BaseSyncedStore] waitForWebSocketConnected timed out after ${timeoutMs}ms — initialize() will return but the next mutation may race the upgrade.`);
+                getContext().logger.debug(`[BaseSyncedStore] waitForWebSocketConnected timed out after ${timeoutMs}ms — initialize() will return but the next mutation may race the upgrade.`);
                 resolve(false);
             }, timeoutMs);
         });
@@ -1519,7 +1519,9 @@ export class BaseSyncedStore {
             // SECURITY: Clear IndexedDB data on session expiry.
             // When auth is revoked, locally cached data must not persist on disk.
             this.database.clear().catch((clearErr) => {
-                getContext().logger.error('[BaseSyncedStore] Failed to clear database on session error', clearErr);
+                // consumer register: session ended, but cached data may remain on disk
+                getContext().logger.error('Your session ended, but some locally cached data could not be cleared from this device.');
+                getContext().logger.debug('[BaseSyncedStore] Failed to clear database on session error', clearErr);
             });
             this.objectPool.clear();
         });
@@ -1533,7 +1535,9 @@ export class BaseSyncedStore {
             this.updateSyncStatus({ state: 'offline', offlineSince: new Date() });
         });
         const onReconnectFailed = this.syncWebSocket.subscribe('reconnect_failed', ({ attempts }) => {
-            getContext().logger.warn('[BaseSyncedStore] WebSocket reconnection gave up', { attempts });
+            // consumer register: reconnection exhausted — the app is now offline
+            getContext().logger.warn('Lost connection to the sync service and could not reconnect. Your app is now offline; changes will sync once the connection is restored.');
+            getContext().logger.debug('[BaseSyncedStore] WebSocket reconnection gave up', { attempts });
             this.updateSyncStatus({ state: 'reconnecting' });
         });
         this.disposers.push(onConnected, onDisconnected, onReconnecting, onDelta, onDeltaBatch, onBootstrapRequired, onBootstrapData, onPresenceUpdate, onError, onSessionError, onHandshakeFailed, onReconnectFailed, () => { this.areaOfInterest?.dispose(); this.areaOfInterest = null; });
@@ -2126,7 +2130,7 @@ export class BaseSyncedStore {
             modelId: 'batch',
             error: error instanceof Error ? error : new Error(String(error)),
         });
-        getContext().logger.error('[BaseSyncedStore] Delta flush error', {
+        getContext().logger.debug('[BaseSyncedStore] Delta flush error', {
             error: error instanceof Error ? error.message : String(error),
         });
     };

package/dist/Database.js

@@ -436,7 +436,7 @@ export class Database {
                 }
                 const store = this.getStore(modelName, 'bootstrap');
                 if (!store) {
-                    getContext().logger.warn(`[Bootstrap] NO IDB STORE for ${modelName} — ${modelData.length} items DROPPED`);
+                    getContext().logger.debug(`[Bootstrap] NO IDB STORE for ${modelName} — ${modelData.length} items DROPPED`);
                     continue;
                 }
                 let writeErrors = 0;
@@ -1023,7 +1023,7 @@ export class Database {
                 // `DataError`, `AbortError`) so we can find what's wrong with
                 // the `compacted` payload shape or store schema.
                 const idbErr = err instanceof Error ? err : new Error(String(err));
-                getContext().logger.warn('[Database.processDeltaBatch] store tx FAILED', {
+                getContext().logger.debug('[Database.processDeltaBatch] store tx FAILED', {
                     modelName,
                     storeDeltasCount: storeDeltas.length,
                     errorName: idbErr.name,
@@ -1071,7 +1071,7 @@ export class Database {
             // persisted" signal loud when it actually happens. If this fires
             // repeatedly on the same sync IDs, a specific row is un-writable
             // (validation? compact issue?) and needs fixing at that layer.
-            getContext().logger.warn('[Database.processDeltaBatch] cursor withheld due to failed store tx', {
+            getContext().logger.debug('[Database.processDeltaBatch] cursor withheld due to failed store tx', {
                 seen: highestSyncId,
                 persisted: highestPersistedSyncId,
                 gap: highestSyncId - highestPersistedSyncId,

package/dist/ObjectPool.js

@@ -232,7 +232,9 @@ export class ObjectPool {
                 // Warn about suspicious patterns
                 if (deltaInfo.action === 'I' &&
                     (history.lastAction === 'U' || history.lastAction === 'D')) {
-                    getContext().logger.warn(`ObjectPool.add() SUSPICIOUS: INSERT after ${history.lastAction}`, { modelType, id, syncId: deltaInfo.syncId });
+                    // Internal delta-ordering anomaly that reconciles on the next
+                    // catch-up — forensic, not consumer-actionable → debug.
+                    getContext().logger.debug(`ObjectPool.add() SUSPICIOUS: INSERT after ${history.lastAction}`, { modelType, id, syncId: deltaInfo.syncId });
                 }
             }
             // Update delta history
@@ -609,7 +611,9 @@ export class ObjectPool {
         const Constructor = ModelClass || this.registry.getModelByName(modelName);
         if (!Constructor) {
             if (!ModelClass && modelName === 'Unknown') {
-                getContext().logger.warn('ObjectPool.createFromData: No model identifier found', { data });
+                // Malformed row with no type marker — dropped, but nothing the consumer
+                // can act on (the actionable schema-drift case is handled below) → debug.
+                getContext().logger.debug('ObjectPool.createFromData: No model identifier found', { data });
                 getContext().modelDebugLogger?.logError('Unknown', 'CREATE', 'No model identifier found', data);
                 return null;
             }
@@ -620,7 +624,11 @@ export class ObjectPool {
                     `. The schema pushed to this org may differ from your local ` +
                     `schema — run \`ablo status\` to compare.`, { code: 'model_not_registered' });
             }
-            getContext().logger.warn(`ObjectPool.createFromData: No constructor found for model "${modelName}"`, { data });
+            // Genuinely actionable and NOT self-healing: a model the server is sending
+            // isn't in your schema, so these rows are silently skipped. Keep at warn,
+            // consumer register (their model name + the `ablo status` fix); forensics ride debug.
+            getContext().logger.warn(`Received data for "${modelName}", which isn't in your schema — these rows will be skipped. Run \`ablo status\` to compare your local schema with the server.`);
+            getContext().logger.debug(`ObjectPool.createFromData: No constructor found for model "${modelName}"`, { data });
             getContext().modelDebugLogger?.logError(modelName, 'CREATE', `No constructor found for model "${modelName}"`, data);
             return null;
         }
@@ -646,7 +654,9 @@ export class ObjectPool {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            getContext().logger.warn(`[ObjectPool.createFromData] FAILED ${modelName}`, { errorMessage, stack: error instanceof Error ? error.stack : undefined });
+            // Internal construction failure — captured via observability below and
+            // re-fetched on resync; the stack is forensic → debug.
+            getContext().logger.debug(`[ObjectPool.createFromData] FAILED ${modelName}`, { errorMessage, stack: error instanceof Error ? error.stack : undefined });
             getContext().observability.captureTransactionFailure({
                 context: 'createFromData',
                 modelName,

package/dist/SyncClient.js

@@ -210,7 +210,13 @@ export class SyncClient extends EventEmitter {
                     // cascade), don't re-add it — Object.assign cannot restore the private
                     // isDisposed flag, so the model would be added in a broken state.
                     if (model.disposed) {
-                        getContext().logger.warn('[SyncClient] Skipping rollback restore for disposed model', {
+                        // Follow-on of an already-logged permanent error, not its own
+                        // problem: the tx that failed has already surfaced the cause in
+                        // TransactionQueue. Restoring a disposed model is a no-op by
+                        // design (can't revive the private isDisposed flag), so keep this
+                        // at `debug` instead of emitting a second `warn` that reads as a
+                        // distinct failure in the console.
+                        getContext().logger.debug('[SyncClient] Rollback skipped restore (model already disposed)', {
                             modelId: transaction.modelId,
                             modelName: transaction.modelName,
                             reason,
@@ -1007,8 +1013,14 @@ export class SyncClient extends EventEmitter {
         // this class of misconfiguration surfaces in dev instead of
         // manifesting as "my drag doesn't save."
         if (!this.userId || !this.organizationId) {
-            getContext().logger.warn('[sync] mutations dropped — SyncClient has no identity. ' +
-                'Did the store call `syncClient.initialize(userId, orgId)`?', {
+            // Internal invariant, not a consumer-actionable error: identity (user +
+            // org) hasn't arrived yet. The mutations stay queued and retry once it
+            // does, so this is `debug` — a transient startup race is normal. If it
+            // never clears it means the host app finished sign-in without seeding
+            // identity, which surfaces downstream as "writes never confirm"; we do
+            // NOT name internal wiring (`SyncClient.initialize`) here because that
+            // method isn't part of the @abloatai/ablo surface a reader could act on.
+            getContext().logger.debug('[sync] writes waiting for identity (user/org not set yet) — queued, will retry', {
                 pending: this.pendingMutations.length,
                 userId: this.userId,
                 organizationId: this.organizationId,
@@ -1601,7 +1613,9 @@ export class SyncClient extends EventEmitter {
                     // re-fetch and re-apply. Logged here so silent IDB failures
                     // are observable instead of disappearing into a default switch
                     // fall-through.
-                    getContext().logger.warn('[SyncClient.applyDeltaBatchToPool] skipping pool op for unpersisted delta', {
+                    // Self-healing: the next catch-up poll / reconnect re-fetches and
+                    // re-applies this delta, so it's forensic, not consumer-actionable → debug.
+                    getContext().logger.debug('[SyncClient.applyDeltaBatchToPool] skipping pool op for unpersisted delta', {
                         modelName,
                         modelId: modelId.slice(0, 12),
                     });

package/dist/agent/Agent.js

@@ -145,7 +145,9 @@ export class Agent {
                 await this.opts.announcer.announce(status, activity);
             }
             catch (err) {
-                this.opts.logger.warn('[perception] announcer error', {
+                // Best-effort presence; failing only means peers don't see this
+                // agent's status. Not consumer-actionable → maintainer register.
+                this.opts.logger.debug('[perception] announcer error', {
                     error: err.message,
                 });
             }
@@ -160,11 +162,11 @@ export class Agent {
                 syncGroups: this.opts.syncGroups,
             });
             if (!res.ok) {
-                this.opts.logger.warn(`[perception] announce failed: ${res.status} ${res.statusText}`);
+                this.opts.logger.debug(`[perception] announce failed: ${res.status} ${res.statusText}`);
             }
         }
         catch (err) {
-            this.opts.logger.warn('[perception] announce error', {
+            this.opts.logger.debug('[perception] announce error', {
                 error: err.message,
             });
         }

package/dist/agent/session.js

@@ -21,6 +21,7 @@
  */
 import { Ablo } from '../client/Ablo.js';
 import { AbloConnectionError } from '../errors.js';
+import { getContext } from '../context.js';
 /**
  * Returns a session whose `getAgent` method handles cache, mint,
  * sync_groups alignment, and lifecycle. Call `disposeAll()` from
@@ -100,12 +101,14 @@ export function createAgentSession(options) {
                 await agent.dispose();
             }
             catch { /* ignore */ }
-            // Use console.error directly (rather than the engine logger)
-            // because this path may run before the per-agent logger is
-            // attached. The structured fields match the cap-mint logger in
-            // `connectAgent.ts` so a single search picks both up.
-            // eslint-disable-next-line no-console
-            console.error('[Agent.session] ws bootstrap failed', {
+            // Route through the gated logger so this obeys ABLO_LOG_LEVEL like every
+            // other line: a plain consumer-register `error` headline (the unreachable
+            // URL + code), with the structured fields on a `debug` companion. The
+            // companion's shape matches the cap-mint logger in `connectAgent.ts` so a
+            // single search picks both up.
+            const log = getContext().logger;
+            log.error(`Agent could not connect to the sync server at ${wsUrl}${code ? ` (${code})` : ''}.`);
+            log.debug('[Agent.session] ws bootstrap failed', {
                 url: wsUrl,
                 surfaceClass: identity.surfaceClass,
                 orgId: identity.organizationId,

package/dist/ai-sdk/coordinated-tool.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `coordinatedTool` — the one-liner that turns an Ablo model write into a Vercel
+ * AI SDK tool with multi-agent coordination already handled, so an AI agent can
+ * contribute to shared state without ever silently clobbering a concurrent
+ * writer.
+ *
+ * The base `./ai-sdk` pattern (see index.ts) is "write your own `tool()` and
+ * call `ablo.<model>.update({ id, data, claim })` inside `execute`". That's the
+ * right amount of control when a tool does something bespoke. But the *common*
+ * case — "the agent produced some content; save it into the shared row" — should
+ * not require every integration to re-derive optimistic concurrency by hand. This
+ * collapses it to a declaration:
+ *
+ * ```ts
+ * import { coordinatedTool } from '@abloatai/ablo/ai-sdk';
+ * import { z } from 'zod';
+ *
+ * const saveSection = coordinatedTool(ablo.documents, {
+ *   description: 'Save your section into the shared document.',
+ *   inputSchema: z.object({ text: z.string() }),
+ *   id: () => DOC_ID,
+ *   apply: (current, { text }) => ({ content: appendBlock(current.content, text) }),
+ *   // strategy: 'merge'  ← the default
+ * });
+ *
+ * await streamText({ model, messages, tools: { saveSection } });
+ * ```
+ *
+ * `apply` is the whole API: a pure function of `(freshest row, tool input) →
+ * patch`, exactly like React's `setState(prev => next)`. Everything underneath —
+ * reading the latest row, the compare-and-swap, the jittered backoff between
+ * reconcile rounds, releasing claims — is the runtime's job, not yours.
+ *
+ * ## Strategies (pick by how writers should relate; all verified to converge
+ * under N-way agent contention)
+ *
+ * - `'merge'` *(default)* — delegates straight to the functional update
+ *   `ablo.<model>.update(id, current => apply(current, input))`. The SDK re-reads
+ *   and re-applies `apply` on top of every concurrent write and backs off between
+ *   rounds, so N agents *accumulate* into one row and the model never sees a
+ *   conflict. **Requires the model's agent conflict policy to be `reject`** (the
+ *   default, or `agentsReject()`); a model declaring `agentsNotify()` HOLDS the
+ *   losing write instead of rejecting it, which defeats the reconcile — use
+ *   `claim`/`queue` there, or switch the policy.
+ *
+ * - `'claim'` — mutual exclusion. Takes a fail-fast claim; if another participant
+ *   holds the row it returns `{ status: 'claimed' }` so the *model* decides to
+ *   retry (a legible signal beats a hidden wait when the agent might do something
+ *   better with its turn). Works regardless of conflict policy.
+ *
+ * - `'queue'` — fair-ish serialization over stateless HTTP, the SQS shape: a
+ *   client poll-acquire loop (true FIFO needs a socket) until the claim is granted
+ *   or `poll.timeoutMs` elapses. The model calls once and the tool waits its turn.
+ */
+import type { z } from 'zod';
+import type { ModelOperations } from '../client/createModelProxy.js';
+export type CoordinationStrategy = 'merge' | 'claim' | 'queue';
+/** The structured result the tool hands back to the model (or the caller). */
+export interface CoordinatedWriteResult<T> {
+    /**
+     * `'written'` — saved. `'claimed'` — another participant holds the row; NOT
+     * saved, the model should try again. `'timeout'` — the queue strategy could not
+     * acquire the row within `poll.timeoutMs`.
+     */
+    status: 'written' | 'claimed' | 'timeout';
+    /** The reconciled row, on `'written'`. */
+    row?: T;
+    message?: string;
+    /** On `'written'` via the `queue` strategy, how long the tool waited in line. */
+    waitedMs?: number;
+}
+export interface CoordinatedToolOptions<TInput, T> {
+    /** Tool description shown to the model. */
+    description: string;
+    /** What the model may send — a normal AI SDK / zod input schema. */
+    inputSchema: z.ZodType<TInput>;
+    /** Which row this write targets, derived from the tool input. */
+    id: (input: TInput) => string;
+    /**
+     * Produce the write patch from the freshest current row + the tool input — a
+     * pure `(prev, input) => next`. Under `merge` it re-runs on every concurrent
+     * write, so it must be idempotent w.r.t. its own contribution (e.g. skip if its
+     * marker is already present) to be safe across reconcile rounds.
+     */
+    apply: (current: T, input: TInput) => Partial<T>;
+    /** How concurrent writers relate. Defaults to `'merge'`. */
+    strategy?: CoordinationStrategy;
+    /** Human-legible coordination metadata attached to the claim (`claim`/`queue`). */
+    claim?: {
+        reason?: string;
+        description?: string;
+    };
+    /** Reconcile budget for `merge` (rounds before `AbloContentionError`). */
+    retries?: number;
+    /** Poll cadence / ceiling for `queue` (defaults 250ms / 30s). */
+    poll?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    };
+}
+export declare function coordinatedTool<TInput, T = Record<string, unknown>, CreateInput = Partial<T>>(model: ModelOperations<T, CreateInput>, options: CoordinatedToolOptions<TInput, T>): import("ai").Tool<TInput, CoordinatedWriteResult<T>>;

package/dist/ai-sdk/coordinated-tool.js

@@ -0,0 +1,129 @@
+/**
+ * `coordinatedTool` — the one-liner that turns an Ablo model write into a Vercel
+ * AI SDK tool with multi-agent coordination already handled, so an AI agent can
+ * contribute to shared state without ever silently clobbering a concurrent
+ * writer.
+ *
+ * The base `./ai-sdk` pattern (see index.ts) is "write your own `tool()` and
+ * call `ablo.<model>.update({ id, data, claim })` inside `execute`". That's the
+ * right amount of control when a tool does something bespoke. But the *common*
+ * case — "the agent produced some content; save it into the shared row" — should
+ * not require every integration to re-derive optimistic concurrency by hand. This
+ * collapses it to a declaration:
+ *
+ * ```ts
+ * import { coordinatedTool } from '@abloatai/ablo/ai-sdk';
+ * import { z } from 'zod';
+ *
+ * const saveSection = coordinatedTool(ablo.documents, {
+ *   description: 'Save your section into the shared document.',
+ *   inputSchema: z.object({ text: z.string() }),
+ *   id: () => DOC_ID,
+ *   apply: (current, { text }) => ({ content: appendBlock(current.content, text) }),
+ *   // strategy: 'merge'  ← the default
+ * });
+ *
+ * await streamText({ model, messages, tools: { saveSection } });
+ * ```
+ *
+ * `apply` is the whole API: a pure function of `(freshest row, tool input) →
+ * patch`, exactly like React's `setState(prev => next)`. Everything underneath —
+ * reading the latest row, the compare-and-swap, the jittered backoff between
+ * reconcile rounds, releasing claims — is the runtime's job, not yours.
+ *
+ * ## Strategies (pick by how writers should relate; all verified to converge
+ * under N-way agent contention)
+ *
+ * - `'merge'` *(default)* — delegates straight to the functional update
+ *   `ablo.<model>.update(id, current => apply(current, input))`. The SDK re-reads
+ *   and re-applies `apply` on top of every concurrent write and backs off between
+ *   rounds, so N agents *accumulate* into one row and the model never sees a
+ *   conflict. **Requires the model's agent conflict policy to be `reject`** (the
+ *   default, or `agentsReject()`); a model declaring `agentsNotify()` HOLDS the
+ *   losing write instead of rejecting it, which defeats the reconcile — use
+ *   `claim`/`queue` there, or switch the policy.
+ *
+ * - `'claim'` — mutual exclusion. Takes a fail-fast claim; if another participant
+ *   holds the row it returns `{ status: 'claimed' }` so the *model* decides to
+ *   retry (a legible signal beats a hidden wait when the agent might do something
+ *   better with its turn). Works regardless of conflict policy.
+ *
+ * - `'queue'` — fair-ish serialization over stateless HTTP, the SQS shape: a
+ *   client poll-acquire loop (true FIFO needs a socket) until the claim is granted
+ *   or `poll.timeoutMs` elapses. The model calls once and the tool waits its turn.
+ */
+import { tool } from 'ai';
+import { AbloClaimedError, AbloNotFoundError } from '../errors.js';
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export function coordinatedTool(model, options) {
+    const strategy = options.strategy ?? 'merge';
+    return tool({
+        description: options.description,
+        inputSchema: options.inputSchema,
+        execute: async (input) => {
+            const id = options.id(input);
+            if (strategy === 'merge') {
+                // The setState of the data layer: read fresh → apply → CAS → re-read +
+                // re-apply with backoff on any concurrent write. Self-healing; the model
+                // never sees a conflict. (Backoff lives in the shared reconcile loop.)
+                const row = await model.update(id, (current) => options.apply(current, input), {
+                    retries: options.retries,
+                });
+                return { status: 'written', row: row ?? undefined };
+            }
+            // claim / queue both take a claim, write under it, and release. The only
+            // difference is what they do when the row is already held: claim returns the
+            // signal to the model; queue waits and retries (SQS-style poll-acquire).
+            const acquireWriteRelease = async () => {
+                const claim = await model.claim({
+                    id,
+                    queue: false,
+                    reason: options.claim?.reason,
+                    description: options.claim?.description,
+                });
+                try {
+                    const current = await model.retrieve({ id });
+                    if (current === undefined) {
+                        throw new AbloNotFoundError(`Cannot write ${id}: it does not exist (or is outside this credential's scope).`, [id]);
+                    }
+                    const row = await model.update({ id, data: options.apply(current, input), claim, wait: 'confirmed' });
+                    return { status: 'written', row };
+                }
+                finally {
+                    await claim.release();
+                }
+            };
+            if (strategy === 'claim') {
+                try {
+                    return await acquireWriteRelease();
+                }
+                catch (e) {
+                    if (e instanceof AbloClaimedError) {
+                        return { status: 'claimed', message: 'Another participant holds this row right now — it was NOT saved. Wait briefly and try again.' };
+                    }
+                    throw e;
+                }
+            }
+            // strategy === 'queue': SQS-style poll-acquire over stateless HTTP.
+            const interval = options.poll?.intervalMs ?? 250;
+            const timeout = options.poll?.timeoutMs ?? 30_000;
+            const start = Date.now();
+            for (;;) {
+                try {
+                    const result = await acquireWriteRelease();
+                    return { ...result, waitedMs: Date.now() - start };
+                }
+                catch (e) {
+                    if (e instanceof AbloClaimedError) {
+                        if (Date.now() - start >= timeout) {
+                            return { status: 'timeout', message: `Could not acquire the row within ${timeout}ms.` };
+                        }
+                        await sleep(interval);
+                        continue;
+                    }
+                    throw e;
+                }
+            }
+        },
+    });
+}

package/dist/ai-sdk/index.d.ts

@@ -71,6 +71,48 @@
  * `wrapWithMultiplayer` is optional. Use it when the whole model call is scoped
  * to one entity before any tool is chosen; tool implementations stay exactly
  * the same.
+ *
+ * ## Multi-agent coordination — the canonical way
+ *
+ * When several agents (or agents + humans) write the SAME row concurrently, the
+ * outcome is decided by **(write path) × (the model's conflict policy)**, NOT by
+ * how smart the model is. The same model silently loses 3 of 4 concurrent
+ * contributions through a blind whole-row write, and lands all 4 through a
+ * coordinated one — because the coordinated write returns a *signal* the model
+ * (or the runtime) acts on. Two empirical laws fall out:
+ *
+ *   1. **Surface the signal.** A write that swallows the conflict and reports
+ *      success is the footgun. Every robust path returns a legible result
+ *      (`reject` → re-read & retry; `claimed` → the model tries again) instead of
+ *      clobbering. Reaching for a bigger model does not fix a silent write.
+ *   2. **Back off.** Under N-way contention, writers that retry in lock-step just
+ *      re-collide. The shared reconcile loop already jitters its backoff; any
+ *      hand-rolled retry must too, or it exhausts its budget and drops a writer.
+ *
+ * `coordinatedTool` (below) encodes both. Prefer it over a hand-written tool for
+ * "save the agent's contribution into the shared row":
+ *
+ * ```ts
+ * import { coordinatedTool } from '@abloatai/ablo/ai-sdk';
+ * const saveSection = coordinatedTool(ablo.documents, {
+ *   description: 'Save your section into the shared document.',
+ *   inputSchema: z.object({ text: z.string() }),
+ *   id: () => DOC_ID,
+ *   apply: (current, { text }) => ({ content: appendBlock(current.content, text) }),
+ *   strategy: 'merge', // 'merge' (default, self-healing) | 'claim' | 'queue'
+ * });
+ * ```
+ *
+ * | strategy | writers relate by | on contention | model conflict policy |
+ * |----------|-------------------|---------------|------------------------|
+ * | `merge`  | accumulate (CAS)  | re-read + re-apply (silent, backed off) | must be `reject` (default) |
+ * | `claim`  | mutual exclusion  | returns `{status:'claimed'}` → model retries | any |
+ * | `queue`  | FIFO-ish (SQS)    | poll-acquire until granted / timeout | any |
+ *
+ * Note: a model declaring `agentsNotify()` HOLDS a losing write instead of
+ * rejecting it, which defeats `merge`'s reconcile (the loser is dropped, not
+ * retried). Use `agentsReject()` for accumulate semantics, or `claim`/`queue`.
  */
 export { coordinationContextMiddleware, type CoordinationContextMiddlewareOptions, type ClaimTarget, } from './coordination-context.js';
 export { wrapWithMultiplayer, type WrapWithMultiplayerOptions } from './wrap.js';
+export { coordinatedTool, type CoordinationStrategy, type CoordinatedToolOptions, type CoordinatedWriteResult, } from './coordinated-tool.js';