@abloatai/ablo 0.26.0 → 0.27.0

package/dist/wire/protocol.d.ts

@@ -1,45 +1,38 @@
 /**
- * Cross-boundary protocol TIMING constants — the one place the 30s ping
- * cadence and the claim/presence lease window are defined. Before this leaf
- * existed the pair was copy-pasted across five sites in four modules, kept
- * in sync only by comments ("~3× the 30s ping"); changing the server ping
- * silently skewed the SDK's claim-expiry estimate and presence reaping.
+ * The timing constants both sides of the protocol must agree on: the ping
+ * cadence and the lease window derived from it. Defining them here once keeps
+ * the client and the server from skewing apart — a change to the ping interval
+ * that did not also move the lease window would make claim expiry and presence
+ * timeouts disagree between the two.
  *
- * Consumers (SDK side, relative import):
- *   - `sync/heartbeat.ts` — `HEARTBEAT_INTERVAL_MS`, the SDK's
- *     application-level `{ type: 'ping' }` cadence.
- *   - `client/createModelProxy.ts` — `DEFAULT_LEASE_TTL_MS`, the client's
- *     expiry estimate for a claim taken without an explicit TTL.
+ * {@link PING_INTERVAL_MS} is how often the connection pings to prove it is
+ * alive. {@link LEASE_TTL_MS} is how long a claim or presence entry stays valid
+ * without a renewing ping. On the client, these set the heartbeat cadence and
+ * the fallback expiry for a claim taken without an explicit lease. On the
+ * server, they set the keepalive interval, the lease granted per keepalive, and
+ * the presence-entry lifetime, so a silently disconnected client drops off the
+ * roster within one lease window.
  *
- * Consumers (server side, via `@abloatai/ablo/wire`):
- *   - `apps/sync-server/src/hub/Hub.ts` — the RFC 6455 `ws.ping()`
- *     keepalive interval (the tick that renews claim leases).
- *   - `apps/sync-server/src/hub/claimCoordinator.ts` —
- *     `LEASE_RENEW_TTL_MS`, the lease lifetime granted per keepalive tick.
- *   - `apps/sync-server/src/presence/PresenceStore.ts` — the default
- *     presence-entry TTL (a silently-dead client leaves the roster within
- *     one lease window).
- *
- * INVARIANT: `LEASE_TTL_MS === 3 * PING_INTERVAL_MS`. The lease is renewed
- * on every ping, so a live holder always has ≥ 2 ping intervals of runway,
- * and a silent one lapses ~2 missed pings after it stops renewing. TTL is
- * liveness, not work-duration — never widen the lease without widening the
- * ping (or holders will flap), and never derive either value locally.
+ * The lease is three ping intervals long and is renewed on every ping, so a
+ * live holder always has at least two intervals of runway and a silent one
+ * lapses about two missed pings after it stops renewing. The window measures
+ * liveness, not how long a task may run: widening the lease without also
+ * widening the ping makes holders flap, and neither value should be redefined
+ * anywhere else.
  */
 export declare const PING_INTERVAL_MS = 30000;
 export declare const LEASE_TTL_MS: number;
 /**
- * WebSocket subprotocols used to carry the bearer credential OUT of the URL.
+ * The WebSocket subprotocols that carry the bearer credential out of the URL.
  *
- * Browsers cannot set an `Authorization` header on a WebSocket, so the SDK
+ * A browser cannot set an `Authorization` header on a WebSocket, so the client
  * offers the token as a `Sec-WebSocket-Protocol` value — `ablo.bearer.<token>` —
  * alongside the real `ablo.sync.v1` protocol the server selects. This keeps the
- * credential out of the query string, which ALB access logs, proxies, and
- * browser history capture. The server reads the token from the subprotocol and
- * echoes back ONLY `ablo.sync.v1`, never the token-bearing value. Lives in
- * `wire/` (not `auth/`) because it IS the wire contract: client and server
- * import the same constants so the handshake format can never drift.
- * Re-exported from `auth/credentialSource.ts` for existing SDK importers.
+ * credential out of the query string, which access logs, proxies, and browser
+ * history would otherwise capture. The server reads the token from the
+ * subprotocol and echoes back only `ablo.sync.v1`, never the token-bearing
+ * value. Both the client and the server import these constants, so the
+ * handshake format cannot drift.
  */
 export declare const WS_BEARER_SUBPROTOCOL_PREFIX = "ablo.bearer.";
 export declare const WS_SYNC_SUBPROTOCOL = "ablo.sync.v1";

package/dist/wire/protocol.js

@@ -1,45 +1,38 @@
 /**
- * Cross-boundary protocol TIMING constants — the one place the 30s ping
- * cadence and the claim/presence lease window are defined. Before this leaf
- * existed the pair was copy-pasted across five sites in four modules, kept
- * in sync only by comments ("~3× the 30s ping"); changing the server ping
- * silently skewed the SDK's claim-expiry estimate and presence reaping.
+ * The timing constants both sides of the protocol must agree on: the ping
+ * cadence and the lease window derived from it. Defining them here once keeps
+ * the client and the server from skewing apart — a change to the ping interval
+ * that did not also move the lease window would make claim expiry and presence
+ * timeouts disagree between the two.
  *
- * Consumers (SDK side, relative import):
- *   - `sync/heartbeat.ts` — `HEARTBEAT_INTERVAL_MS`, the SDK's
- *     application-level `{ type: 'ping' }` cadence.
- *   - `client/createModelProxy.ts` — `DEFAULT_LEASE_TTL_MS`, the client's
- *     expiry estimate for a claim taken without an explicit TTL.
+ * {@link PING_INTERVAL_MS} is how often the connection pings to prove it is
+ * alive. {@link LEASE_TTL_MS} is how long a claim or presence entry stays valid
+ * without a renewing ping. On the client, these set the heartbeat cadence and
+ * the fallback expiry for a claim taken without an explicit lease. On the
+ * server, they set the keepalive interval, the lease granted per keepalive, and
+ * the presence-entry lifetime, so a silently disconnected client drops off the
+ * roster within one lease window.
  *
- * Consumers (server side, via `@abloatai/ablo/wire`):
- *   - `apps/sync-server/src/hub/Hub.ts` — the RFC 6455 `ws.ping()`
- *     keepalive interval (the tick that renews claim leases).
- *   - `apps/sync-server/src/hub/claimCoordinator.ts` —
- *     `LEASE_RENEW_TTL_MS`, the lease lifetime granted per keepalive tick.
- *   - `apps/sync-server/src/presence/PresenceStore.ts` — the default
- *     presence-entry TTL (a silently-dead client leaves the roster within
- *     one lease window).
- *
- * INVARIANT: `LEASE_TTL_MS === 3 * PING_INTERVAL_MS`. The lease is renewed
- * on every ping, so a live holder always has ≥ 2 ping intervals of runway,
- * and a silent one lapses ~2 missed pings after it stops renewing. TTL is
- * liveness, not work-duration — never widen the lease without widening the
- * ping (or holders will flap), and never derive either value locally.
+ * The lease is three ping intervals long and is renewed on every ping, so a
+ * live holder always has at least two intervals of runway and a silent one
+ * lapses about two missed pings after it stops renewing. The window measures
+ * liveness, not how long a task may run: widening the lease without also
+ * widening the ping makes holders flap, and neither value should be redefined
+ * anywhere else.
  */
 export const PING_INTERVAL_MS = 30_000;
 export const LEASE_TTL_MS = 3 * PING_INTERVAL_MS;
 /**
- * WebSocket subprotocols used to carry the bearer credential OUT of the URL.
+ * The WebSocket subprotocols that carry the bearer credential out of the URL.
  *
- * Browsers cannot set an `Authorization` header on a WebSocket, so the SDK
+ * A browser cannot set an `Authorization` header on a WebSocket, so the client
  * offers the token as a `Sec-WebSocket-Protocol` value — `ablo.bearer.<token>` —
  * alongside the real `ablo.sync.v1` protocol the server selects. This keeps the
- * credential out of the query string, which ALB access logs, proxies, and
- * browser history capture. The server reads the token from the subprotocol and
- * echoes back ONLY `ablo.sync.v1`, never the token-bearing value. Lives in
- * `wire/` (not `auth/`) because it IS the wire contract: client and server
- * import the same constants so the handshake format can never drift.
- * Re-exported from `auth/credentialSource.ts` for existing SDK importers.
+ * credential out of the query string, which access logs, proxies, and browser
+ * history would otherwise capture. The server reads the token from the
+ * subprotocol and echoes back only `ablo.sync.v1`, never the token-bearing
+ * value. Both the client and the server import these constants, so the
+ * handshake format cannot drift.
  */
 export const WS_BEARER_SUBPROTOCOL_PREFIX = 'ablo.bearer.';
 export const WS_SYNC_SUBPROTOCOL = 'ablo.sync.v1';

package/dist/wire/protocolVersion.d.ts

@@ -1,56 +1,60 @@
 /**
- * The sync protocol version — ONE monotonically increasing integer covering
- * everything client and server must agree on to speak: WS frame shapes
- * (hub `ClientMessage`/`ServerMessage`), HTTP request/response envelopes, and
- * the persisted delta encodings a client replays. Zero's recipe: schemaHash
- * (WS close 4009) only detects APP-schema drift; this detects PROTOCOL drift —
- * before it, every main-push deploy was an old-client/new-server encounter
- * with no detector at all.
+ * The sync protocol version — a single integer, increasing over time, that
+ * covers everything the client and server must agree on to talk to each other:
+ * the WebSocket frame shapes, the HTTP request and response envelopes, and the
+ * delta encodings a client replays. It is separate from the app-schema hash
+ * (WebSocket close code 4009), which detects drift in your data model; this
+ * detects drift in the protocol itself.
  *
- * Deploy contract: SERVER DEPLOYS FIRST. The server accepts every version in
- * `[MIN_SUPPORTED_PROTOCOL_VERSION, PROTOCOL_VERSION]`; a client never
- * connects to a server older than itself (if it does — a rollback mid-fleet —
- * the too-new rejection below makes it visible instead of undefined behavior).
+ * Deploy ordering: the server is deployed first. It accepts every version in
+ * the inclusive range from {@link MIN_SUPPORTED_PROTOCOL_VERSION} to
+ * {@link PROTOCOL_VERSION}, and a client is never expected to connect to a
+ * server older than itself. If that does happen — for example a partial server
+ * rollback — {@link protocolVersionProblem} reports it as `too_new` so the
+ * mismatch is visible rather than undefined.
  *
- * How to change the protocol:
- *   1. Make the wire change backward-tolerant where possible (the server's
- *      `clientMessageSchema` accepts-and-ignores unknown payload keys — an
- *      ADDITIVE field usually needs NO version bump).
- *   2. For a breaking change: bump `PROTOCOL_VERSION`, append a changelog
- *      entry below, and keep `MIN_SUPPORTED_PROTOCOL_VERSION` covering every
- *      SDK version still in the wild; raise it only with a deprecation window.
- *   3. The contract test (`__tests__/protocolVersion.test.ts`) fails on any
- *      bump — update it in the same change, deliberately.
+ * To change the protocol:
+ *   1. Make the change backward-tolerant where you can. The server ignores
+ *      unknown payload keys, so an additive field usually needs no version bump.
+ *   2. For a breaking change, bump {@link PROTOCOL_VERSION}, add a changelog
+ *      entry below, and keep {@link MIN_SUPPORTED_PROTOCOL_VERSION} low enough
+ *      to cover every client still in use; raise it only after a deprecation
+ *      window.
+ *   3. The protocol-version contract test fails on any bump — update it in the
+ *      same change, deliberately.
  *
- * CHANGELOG
- *   v1 (2026-07-03) — the protocol as of the version field's introduction:
- *      sync_request{cursor,lastSyncId,capabilities,protocolVersion?},
- *      commit/mutation/claim/release/ack/presence_update frames, bootstrap +
- *      delta batches, HTTP envelopes per `wire/errorEnvelope` +
- *      `wire/listEnvelope`. Clients that predate the field send NO
- *      `protocolVersion` — treated as v1 (the field's introduction changed no
- *      semantics).
+ * Changelog
+ *   v1 (2026-07-03) — the protocol as of this field's introduction: the
+ *      sync-request frame (`cursor`, `lastSyncId`, `capabilities`, optional
+ *      `protocolVersion`), the commit, mutation, claim, release, ack, and
+ *      presence-update frames, the bootstrap and delta batches, and the HTTP
+ *      error and list envelopes. A client that predates this field sends no
+ *      `protocolVersion` and is treated as v1, since introducing the field
+ *      changed no behavior.
  */
 export declare const PROTOCOL_VERSION = 1;
 /**
- * Oldest client protocol this build still serves. Raising it is a BREAKING
- * cut for un-upgraded clients — do it only with a deprecation window and a
- * changelog entry.
+ * The oldest client protocol version this build still serves. Raising it cuts
+ * off clients that have not upgraded, so do it only after a deprecation window
+ * and with a changelog entry.
  */
 export declare const MIN_SUPPORTED_PROTOCOL_VERSION = 1;
 /**
- * WS application close code for a protocol-version rejection (4001 =
- * credential, 4009 = app-schema drift). The reason string is the error code
- * `protocol_version_unsupported`; the SDK treats this close as TERMINAL —
- * reconnecting cannot heal a version mismatch, upgrading the SDK (or rolling
- * the server forward) can.
+ * The WebSocket close code the server sends to reject a protocol-version
+ * mismatch. It sits alongside the other application close codes (4001 for a
+ * credential problem, 4009 for app-schema drift), and its reason string is the
+ * error code `protocol_version_unsupported`. A client should treat this close
+ * as terminal: reconnecting cannot heal a version mismatch, but upgrading the
+ * client or rolling the server forward can.
  */
 export declare const WS_CLOSE_PROTOCOL_VERSION = 4010;
 /**
- * Classify a peer's announced protocol version. `undefined` (a pre-versioning
- * client) is v1 by definition. Non-integer garbage classifies as `too_old` —
- * fail closed, visibly.
+ * Classifies a peer's announced protocol version against what this build
+ * supports, returning `'too_old'`, `'too_new'`, or `null` when the versions are
+ * compatible. An `undefined` version — a client from before versioning existed
+ * — counts as v1. A non-integer value is treated as `'too_old'` so the check
+ * fails closed and visibly.
  */
 export declare function protocolVersionProblem(announced: number | undefined): 'too_old' | 'too_new' | null;
-/** HTTP request header carrying the client's protocol version. */
+/** The HTTP request header a client uses to announce its protocol version. */
 export declare const PROTOCOL_VERSION_HEADER = "Ablo-Protocol-Version";

package/dist/wire/protocolVersion.js

@@ -1,55 +1,59 @@
 /**
- * The sync protocol version — ONE monotonically increasing integer covering
- * everything client and server must agree on to speak: WS frame shapes
- * (hub `ClientMessage`/`ServerMessage`), HTTP request/response envelopes, and
- * the persisted delta encodings a client replays. Zero's recipe: schemaHash
- * (WS close 4009) only detects APP-schema drift; this detects PROTOCOL drift —
- * before it, every main-push deploy was an old-client/new-server encounter
- * with no detector at all.
+ * The sync protocol version — a single integer, increasing over time, that
+ * covers everything the client and server must agree on to talk to each other:
+ * the WebSocket frame shapes, the HTTP request and response envelopes, and the
+ * delta encodings a client replays. It is separate from the app-schema hash
+ * (WebSocket close code 4009), which detects drift in your data model; this
+ * detects drift in the protocol itself.
  *
- * Deploy contract: SERVER DEPLOYS FIRST. The server accepts every version in
- * `[MIN_SUPPORTED_PROTOCOL_VERSION, PROTOCOL_VERSION]`; a client never
- * connects to a server older than itself (if it does — a rollback mid-fleet —
- * the too-new rejection below makes it visible instead of undefined behavior).
+ * Deploy ordering: the server is deployed first. It accepts every version in
+ * the inclusive range from {@link MIN_SUPPORTED_PROTOCOL_VERSION} to
+ * {@link PROTOCOL_VERSION}, and a client is never expected to connect to a
+ * server older than itself. If that does happen — for example a partial server
+ * rollback — {@link protocolVersionProblem} reports it as `too_new` so the
+ * mismatch is visible rather than undefined.
  *
- * How to change the protocol:
- *   1. Make the wire change backward-tolerant where possible (the server's
- *      `clientMessageSchema` accepts-and-ignores unknown payload keys — an
- *      ADDITIVE field usually needs NO version bump).
- *   2. For a breaking change: bump `PROTOCOL_VERSION`, append a changelog
- *      entry below, and keep `MIN_SUPPORTED_PROTOCOL_VERSION` covering every
- *      SDK version still in the wild; raise it only with a deprecation window.
- *   3. The contract test (`__tests__/protocolVersion.test.ts`) fails on any
- *      bump — update it in the same change, deliberately.
+ * To change the protocol:
+ *   1. Make the change backward-tolerant where you can. The server ignores
+ *      unknown payload keys, so an additive field usually needs no version bump.
+ *   2. For a breaking change, bump {@link PROTOCOL_VERSION}, add a changelog
+ *      entry below, and keep {@link MIN_SUPPORTED_PROTOCOL_VERSION} low enough
+ *      to cover every client still in use; raise it only after a deprecation
+ *      window.
+ *   3. The protocol-version contract test fails on any bump — update it in the
+ *      same change, deliberately.
  *
- * CHANGELOG
- *   v1 (2026-07-03) — the protocol as of the version field's introduction:
- *      sync_request{cursor,lastSyncId,capabilities,protocolVersion?},
- *      commit/mutation/claim/release/ack/presence_update frames, bootstrap +
- *      delta batches, HTTP envelopes per `wire/errorEnvelope` +
- *      `wire/listEnvelope`. Clients that predate the field send NO
- *      `protocolVersion` — treated as v1 (the field's introduction changed no
- *      semantics).
+ * Changelog
+ *   v1 (2026-07-03) — the protocol as of this field's introduction: the
+ *      sync-request frame (`cursor`, `lastSyncId`, `capabilities`, optional
+ *      `protocolVersion`), the commit, mutation, claim, release, ack, and
+ *      presence-update frames, the bootstrap and delta batches, and the HTTP
+ *      error and list envelopes. A client that predates this field sends no
+ *      `protocolVersion` and is treated as v1, since introducing the field
+ *      changed no behavior.
  */
 export const PROTOCOL_VERSION = 1;
 /**
- * Oldest client protocol this build still serves. Raising it is a BREAKING
- * cut for un-upgraded clients — do it only with a deprecation window and a
- * changelog entry.
+ * The oldest client protocol version this build still serves. Raising it cuts
+ * off clients that have not upgraded, so do it only after a deprecation window
+ * and with a changelog entry.
  */
 export const MIN_SUPPORTED_PROTOCOL_VERSION = 1;
 /**
- * WS application close code for a protocol-version rejection (4001 =
- * credential, 4009 = app-schema drift). The reason string is the error code
- * `protocol_version_unsupported`; the SDK treats this close as TERMINAL —
- * reconnecting cannot heal a version mismatch, upgrading the SDK (or rolling
- * the server forward) can.
+ * The WebSocket close code the server sends to reject a protocol-version
+ * mismatch. It sits alongside the other application close codes (4001 for a
+ * credential problem, 4009 for app-schema drift), and its reason string is the
+ * error code `protocol_version_unsupported`. A client should treat this close
+ * as terminal: reconnecting cannot heal a version mismatch, but upgrading the
+ * client or rolling the server forward can.
  */
 export const WS_CLOSE_PROTOCOL_VERSION = 4010;
 /**
- * Classify a peer's announced protocol version. `undefined` (a pre-versioning
- * client) is v1 by definition. Non-integer garbage classifies as `too_old` —
- * fail closed, visibly.
+ * Classifies a peer's announced protocol version against what this build
+ * supports, returning `'too_old'`, `'too_new'`, or `null` when the versions are
+ * compatible. An `undefined` version — a client from before versioning existed
+ * — counts as v1. A non-integer value is treated as `'too_old'` so the check
+ * fails closed and visibly.
  */
 export function protocolVersionProblem(announced) {
     const v = announced ?? 1;
@@ -59,5 +63,5 @@ export function protocolVersionProblem(announced) {
         return 'too_new';
     return null;
 }
-/** HTTP request header carrying the client's protocol version. */
+/** The HTTP request header a client uses to announce its protocol version. */
 export const PROTOCOL_VERSION_HEADER = 'Ablo-Protocol-Version';

package/docs/coordination.md

@@ -416,6 +416,65 @@ try {
 }
 ```
 
+### `heartbeat` — holding a claim for long-running work
+
+```ts
+held.heartbeat(ttl?: Duration): Promise<{ expiresAt: number }>
+```
+
+A claim's TTL is crash cleanup, not a work-duration estimate — so a task that
+outlives it (an agent run, a background worker's job) keeps its lease by
+**beating**, the same pattern as an SQS visibility heartbeat or a Temporal
+activity heartbeat. Each beat extends the lease from now (never shortens it,
+and each extension is clamped server-side); a crashed worker stops beating and
+its lease lapses within one beat window, promoting the next waiter.
+
+Usually **implicit** — pass `heartbeat` when claiming and the SDK beats every
+third of the TTL until release:
+
+```ts
+await using claim = await ablo.reports.claim({
+  id: 'report_q3',
+  reason: 'generating',
+  ttl: '5m',
+  heartbeat: true,               // or an explicit cadence: heartbeat: '2m'
+  onHeartbeatLost: () => abortWork(),
+});
+await runLongGeneration(claim.data); // lease held for the duration
+// scope exit releases; the loop stops with it
+```
+
+A beat that comes back with a definitive loss — the lease expired and the
+queue moved on — rejects with `AbloClaimedError` (`claim_lost`) and stops the
+auto-loop. For a worker with no socket, **the failed beat is the loss
+notification**; abandon or re-claim, and remember any write attempted under
+the old lease is independently rejected by its `readAt` guard. Transient
+failures (a connection blip) don't stop the loop — the next tick retries.
+
+Each beat's answer carries two more things:
+
+- **`queueDepth`** — how many participants wait in line behind the lease.
+  This is the cooperative-yield pressure signal: a worker that can checkpoint
+  may release early when others wait. Read it from the resolved beat, or pass
+  `onHeartbeat` when claiming to observe every auto-beat.
+- **progress `details`** — `held.heartbeat({ details: { pages: 42, of: 100 } })`
+  stores the payload as the claim's peer-visible `meta.progress` (last beat
+  wins, via `claim.state`). This is presence, not a checkpoint: it dies with
+  the lease. Durable progress belongs in the data itself — write a row, and
+  every subscriber already sees it.
+
+Works identically on both transports: the realtime client sends a
+`claim_heartbeat` frame; the HTTP client posts
+`POST /v1/models/{model}/{id}/claim/heartbeat` (`{ ttl?, claimId?, details? }`).
+Over HTTP, a **queued** claim can heartbeat too — it refreshes the waiter's
+slot in the line (a queued slot is TTL'd like a lease) and reports
+`{ status: 'queued', position }`.
+
+A stateless worker holding **many** rows beats them all in one round trip:
+`ablo.claims.heartbeatAll({ ttl: '5m' })` → `POST /v1/claims/heartbeat`, one
+entry per extended lease. This is the socketless twin of the realtime
+keepalive, which already renews every held lease on each ping.
+
 ### `watch` — presence for a set of rows
 
 Reading or claiming a row auto-enrolls you in its sync group, which is enough for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -150,10 +150,10 @@
     "pretest": "node scripts/check-dist-fresh.mjs",
     "test": "jest",
     "test:quickstart": "node scripts/test-quickstart.mjs",
-    "test:unit": "jest --testPathPattern=__tests__/unit",
-    "test:integration": "jest --testPathPattern=__tests__/integration",
-    "test:contract": "jest --testPathPattern=__tests__/contract",
-    "test:property": "jest --testPathPattern=__tests__/property",
+    "test:unit": "jest --testPathPatterns __tests__/unit",
+    "test:integration": "jest --testPathPatterns __tests__/integration",
+    "test:contract": "jest --testPathPatterns __tests__/contract",
+    "test:property": "jest --testPathPatterns __tests__/property",
     "test:coverage": "jest --coverage",
     "test:e2e": "E2E_TEST=true jest --config jest.e2e.config.ts",
     "test:e2e:up": "docker compose -f docker-compose.test.yml up -d --wait",
@@ -212,9 +212,9 @@
   "devDependencies": {
     "@ai-sdk/provider": "^3.0.0",
     "@clack/prompts": "^0.11.0",
-    "@jest/globals": "^29.7.0",
+    "@jest/globals": "^30.2.0",
     "@prisma/client": "^7.3.0",
-    "@types/jest": "^29.5.0",
+    "@types/jest": "^30.0.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/uuid": "^10.0.0",
@@ -225,13 +225,14 @@
     "fake-indexeddb": "^6.0.0",
     "fast-check": "^3.0.0",
     "globals": "^16.5.0",
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "jest-environment-node": "^30.2.0",
     "picocolors": "^1.1.0",
     "postgres": "^3.4.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "ts-jest": "^29.4.0",
+    "ts-jest": "^29.4.5",
     "ts-morph": "^26.0.0",
     "tsup": "^8.0.0",
     "tsx": "^4.19.0",

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

@@ -1,101 +0,0 @@
-/**
- * `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>>;