@abloatai/ablo 0.61.0 → 0.63.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.63.0
+
+Reactive model clients now expose live awareness beneath the model namespace.
+`usePresence((ablo) => ablo.chats, chatId)` owns the mounted view's read
+activity, refresh, reconnect announcement, and cleanup, and returns the human
+and agent sessions active on that record. Multiple tabs remain distinct
+authenticated sessions.
+
+Transient collaboration now uses `ablo.<model>.events`. Applications can send
+and subscribe to cursor, selection, and similar signals by record id without
+putting routing or caller-authored identity in the payload. Ablo derives the
+record sync group, routes only to other connections in that group, and supplies
+the authenticated participant, presence session, and server timestamp to the
+receiver.
+
+Model events are deliberately lossy: disconnected sends are dropped and
+events are not replayed after reconnect. Persist state that must recover as
+ordinary model data, and throttle high-frequency pointer updates in the
+application. The legacy store-level collaboration-event API remains available
+and now receives optional authenticated context from updated servers.
+
+## 0.62.0
+
+Every live client now exposes one session-owned `ablo.presence` projection.
+`active` shows the current session's announced activity and `others` shows the
+other visible sessions. The reactive client adds `forModel(model, id?)` to
+narrow the same projection without opening another connection. Read, claim,
+create, update, and delete activity share one typed, model-addressable contract
+and remain attributable to their originating human or agent session.
+
+Claims and presence now have separate owners: the durable claim authority
+decides admission, queuing, fencing, expiry, and release, while presence
+projects that lifecycle for live collaborators. Cross-replica HTTP callers
+resolve and release claims against the shared authority instead of a
+process-local roster. An object-form claim also returns its protected row
+snapshot in the acquisition request, removing the post-grant read race and an
+extra round trip.
+
+This replaces the earlier participant-oriented presence stream and its raw
+wire event vocabulary. Migrate `PresenceStream`, `Peer`, `Activity`,
+`PresenceUpdate*`, and `PresenceKind` consumers to `Ablo.Presence`,
+`Ablo.PresenceSession`, and `Ablo.PresenceActivity`; read the projection through
+`ablo.presence.active`, `ablo.presence.others`, or
+`ablo.presence.forModel(model, id?)`. The low-level `presence_update` event,
+frame-handler members, presence schemas, and claim-stream participant setters
+are removed because session identity and typed presence snapshot/patch frames
+now own that lifecycle.
+
+Admission and other transient failures now expose machine-actionable
+`recovery`, `retryable`, and `retryAfterSeconds` fields through the branded
+package, including session issuance and headless model requests. The headless
+client automatically replays an admission-rejected request after the requested
+delay, without restarting the surrounding claim workflow. Queued HTTP claims
+heartbeat through their known model and row target, so one holder releasing
+cannot make the next queued ticket appear lost during promotion. A visibility
+miss while the fence is minted is retried only inside the ticket's last
+server-acknowledged lease window.
+
 ## 0.61.0
 
 ### Existing database connections repair in place

package/dist/coordination.d.ts

@@ -2,9 +2,9 @@ export * from '@abloatai/transaction/coordination';
 /**
  * Coordination vocabulary that the streams module declares.
  *
- * A caller that holds a claim, watches presence, or types an activity feed
- * needs these names, and coordination is where they belong — so they are
+ * A caller that holds a claim needs these names, and coordination is where
+ * they belong — so they are
  * surfaced here rather than leaving callers to reach into the type module.
  */
-export type { Activity, Claim, ClaimTarget } from '@abloatai/transaction/types/streams';
+export type { Claim, ClaimTarget } from '@abloatai/transaction/types/streams';
 //# sourceMappingURL=coordination.d.ts.map

package/dist/coordination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coordination.d.ts","sourceRoot":"","sources":["../src/coordination.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AAEnD;;;;;;GAMG;AACH,YAAY,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC"}
+{"version":3,"file":"coordination.d.ts","sourceRoot":"","sources":["../src/coordination.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AAEnD;;;;;;GAMG;AACH,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC"}

package/docs/api.md

@@ -66,6 +66,9 @@ Each schema model becomes a typed model on the client:
 - `ablo.weatherReports.update({ id, data, ...options })` updates a row.
 - `ablo.weatherReports.delete({ id, ...options })` deletes a row.
 - `ablo.weatherReports.claim({ id, description })` acquires a durable write lease; the HTTP form is awaited.
+- `ablo.weatherReports.presence(id)` reads the live session projection for one row on a reactive client.
+- `ablo.weatherReports.events.send(id, name, payload)` sends a transient row-scoped event on a reactive client.
+- `ablo.weatherReports.events.subscribe(id, name, handler)` subscribes to that transient event and returns a disposer.
 
 `local.` narrows a query to what has already synced. `get({ id })`, `read({ id })`, and
 `list({ where })` answer from the local graph and fall back to IndexedDB and
@@ -91,11 +94,48 @@ fallback removed — nothing to await, so they return a value.
 | `claim.queue({ id })` | `Promise<ClaimQueueView>` on HTTP | You need the durable wait line. |
 | `claim.release({ id })` | `Promise<void>` on HTTP | You need to release a claim early. |
 | `claim.reorder({ id, order })` | `Promise<void>` on HTTP | A privileged coordinator needs to reorder the wait line. |
+| `presence(id?)` | `readonly PresenceSession[]` on reactive clients | You need the sessions currently active on a model or row. |
+| `events.send(id, name, payload)` | `void` on reactive clients | You need to send a cursor, selection, or other transient signal. |
+| `events.subscribe(id, name, handler)` | `() => void` on reactive clients | You need transient signals for one row until cleanup. |
 
 `get`, `read`, `list`, `create`, `update`, `delete`, and `claim` go
 through the server. The `local` reads work off the rows a session has already
 synced, so a cheap re-read needs no round-trip.
 
+### Live presence and model events
+
+Presence and events belong to the reactive WebSocket client. They are not on
+the stateless HTTP client used by server-side agents and workers.
+
+Use presence for who is active on a row. In React, `usePresence` also owns the
+mounted component's read activity and cleanup:
+
+```tsx
+const viewers = usePresence((ablo) => ablo.chats, chatId);
+```
+
+Use model events for short-lived UI detail that should not become a database
+field:
+
+```ts
+const stop = ablo.files.events.subscribe(fileId, 'cursor', (cursor, context) => {
+  renderCursor(context.sender.presenceSessionId, cursor);
+});
+
+ablo.files.events.send(fileId, 'cursor', { line: 12, column: 4 });
+stop();
+```
+
+The model and row determine the sync group. Ablo excludes the sending
+connection, validates the wire envelope, and supplies authenticated
+`context.sender` and `context.sentAt`; identity does not belong in the payload.
+Event names are strings and payloads are objects. Payloads are not inferred
+from the schema today.
+
+Delivery is lossy: sending while disconnected is dropped, and events are not
+replayed after reconnect. Cursor and live selection fit this contract. Persist
+anything that must be recovered as ordinary model data.
+
 ## Atomic commits
 
 Use one `ablo.commits.create` when several Ablo model writes must all land or

package/docs/client-behavior.md

@@ -157,13 +157,20 @@ see. Options on the claim:
 - `{ maxQueueDepth }` rejects if the wait line is already too deep.
 
 While waiting, schema clients learn when the claim clears from the live claim
-stream, so they never poll.
+stream, so they never poll. Headless HTTP clients poll the same durable queue;
+the model client keeps the row target on each heartbeat, so a holder releasing
+cannot make the queued ticket unresolvable by id. During fence minting, it also
+keeps polling through a visibility miss only while the server's last enqueue or
+heartbeat acknowledgement still guarantees that ticket is live.
 
 ## Errors
 
 All SDK errors extend `AbloError`. `type` is the class-name discriminator, such
 as `AbloStaleContextError`; `code` is the wire condition, such as
 `stale_context`. Use `instanceof` in-process and `type` after serialization.
+Every error also exposes a typed `recovery` classification and `retryable`
+boolean. When the server requests a minimum delay, `retryAfterSeconds` is
+present on the same error for both 429 and 503 responses.
 
 | Error | Typical cause |
 |---|---|
@@ -196,8 +203,14 @@ Model writes are retry-safe by default because the SDK attaches an idempotency
 key. If you provide your own key, keep it stable for retries of the same logical
 operation and never reuse it for a different payload.
 
-Retry transport failures and 5xx with backoff. Do not blindly retry validation,
-permission, idempotency, or stale-context errors without changing the request.
+Retry transport failures and 5xx with backoff. For example, an
+`instance_at_capacity` error has `recovery === 'transient'`; wait at least
+`retryAfterSeconds` before replaying the unchanged request. The headless HTTP
+client performs that exact replay within `timeoutMs`; importantly, it does not
+restart a larger claim/read/write workflow around the rejected request. If the
+deadline is exhausted, the same actionable error reaches the caller. Do not
+blindly retry validation, permission, idempotency, or stale-context errors
+without changing the request.
 
 ## Logging
 

package/docs/integration-guide.md

@@ -523,6 +523,8 @@ that guarantee as eventual completion with repair—not atomicity.
 | `persistence: 'indexeddb'`                | Durable browser cache that survives reloads, for apps that need it. |
 | `durableWrites: { store, namespace? }`     | Recover unacknowledged worker writes after a process restart.      |
 | `claim` / `claim.state` / `claim.queue`          | Show active work and coordinate before a write.                   |
+| `usePresence` / `<model>.presence`         | Show the human and agent sessions active on a row.                 |
+| `<model>.events`                           | Send lossy row-scoped cursor, selection, and similar UI signals.   |
 | `read` + `reads`                          | Reject writes based on stale state.                               |
 | `mutable`, `readOnly`, `field`, `indexed` | Advanced schema and read tuning.                                  |
 
@@ -546,7 +548,16 @@ them.
 | `delete({ id, ...opts })`              | Delete through the model client.                                                 |
 | `claim.state({ id })`                  | See who is currently working on a row (synchronous).                             |
 | `claim({ id, description?, ttl? })`    | Acquire a disposable handle: wait for your turn, re-read, and hold the row.       |
+| `presence(id?)`                        | Read live human and agent sessions on a reactive client.                         |
+| `events.send(id, name, payload)`       | Send a transient row-scoped signal; disconnected sends are dropped.              |
+| `events.subscribe(id, name, handler)`  | Listen until its returned disposer is called; events are not replayed.            |
 
 Keep first integrations on the model methods above. Every mutation and
 server-read verb takes one options object; the synchronous `local.get(id)` stays
 positional.
+
+Presence and events require the reactive WebSocket client. Server-side agents
+using the stateless HTTP client still coordinate through reads, claims, and
+writes, but they do not open a cursor/selection event channel. Event payloads
+carry application data only; Ablo derives the model scope and supplies
+authenticated participant context to receivers.

package/docs/integrations/inngest.md

@@ -242,7 +242,7 @@ examples/
   inngest-agent/              events, functions, steps, endpoint, AI composition
 ```
 
-Do not add Inngest to `packages/agent`. A dedicated `@abloatai/inngest` package
+Do not add Inngest orchestration to the Ablo core. A dedicated `@abloatai/inngest` package
 is justified only after multiple real applications reveal substantial
 reusable behavior beyond a small function or step wrapper.
 

package/docs/integrations/temporal.md

@@ -178,7 +178,7 @@ The repository's
 [`examples/temporal-agent`](../../../../examples/temporal-agent/README.md)
 contains a Workflow, Activities, Worker, client, durable AI SDK tool, and a
 simulated lost-response retry. It is a standalone application on purpose:
-Temporal stays out of Ablo's core packages and out of `packages/agent`.
+Temporal stays out of Ablo's core packages; applications own their agent composition.
 
 A dedicated `@abloatai/temporal` package should be introduced only after
 multiple production integrations reveal substantial, stable behavior that

package/docs/options.md

@@ -200,7 +200,23 @@ connection follows, but it cannot widen the authority granted by
 
 ## collaborationEvents
 
-Application-defined WebSocket event names accepted by `subscribe()`.
+Legacy store-level WebSocket event names accepted by `subscribe()`. New React
+and reactive-client code should prefer the record-scoped
+`ablo.<model>.events.send(...)` and `.subscribe(...)` surface. A
+collaboration-event handler receives the application's unchanged payload first
+and optional server-authenticated context second:
+
+```ts
+store.subscribe('document:cursor', (cursor, context) => {
+  context?.sender.presenceSessionId;
+  context?.sender.participant; // { id, kind }
+  context?.sentAt;
+});
+```
+
+The context is optional while connecting to a server version that predates
+authenticated collaboration-event attribution. Never put caller-authored user
+identity in the application payload.
 
 ## cursorStore
 

package/docs/react.md

@@ -39,10 +39,10 @@ export const ablo = Ablo({
 // The typed binding: capture the schema once, and every component imports
 // born-typed hooks from this file — `useAblo()` takes no type arguments,
 // and a selector's `ablo` parameter knows your models.
-export const { AbloProvider, useAblo } = createAbloReact(schema);
+export const { AbloProvider, useAblo, usePresence } = createAbloReact(schema);
 ```
 
-Import `AbloProvider` and `useAblo` from `lib/ablo` rather than from the
+Import `AbloProvider`, `useAblo`, and `usePresence` from `lib/ablo` rather than from the
 package, and the schema generic never appears at a call site again — the
 same one-binding-file convention as tRPC's `createTRPCReact` or
 react-redux's typed hooks.
@@ -188,6 +188,80 @@ imperative work after an event or effect.
 
 See [API reference](/docs/api) for the full options surface.
 
+## usePresence: viewers and active participants
+
+`usePresence` declares that the mounted component is reading one model record
+and returns the live sessions active on that record. Use the selector form with
+the schema-bound hook:
+
+```tsx
+import { usePresence } from '@/lib/ablo';
+
+export function ChatView({ chatId }: { chatId: string }) {
+  const viewers = usePresence((ablo) => ablo.chats, chatId);
+
+  return viewers.map((session) => (
+    <Avatar
+      key={session.presenceSessionId}
+      participantId={session.participant.id}
+      kind={session.participant.kind}
+    />
+  ));
+}
+```
+
+The component chooses the model and record. Ablo owns the authenticated
+session identity, read lease, refresh, reconnect re-announcement, and removal
+on cleanup. Multiple tabs remain separate sessions, and human and agent
+participants use the same result shape. Do not build a separate `chat:view`
+event, heartbeat, or stale-viewer timer in the app.
+
+If you already have the client, the direct model form is equivalent:
+
+```tsx
+const viewers = usePresence(ablo.chats, chatId);
+```
+
+The hook returns the complete matching session projection, including the
+current session. Use `session.participant` for identity and inspect
+`session.activities` when the UI needs to distinguish reading from claiming or
+writing.
+
+## Model events: cursors and selections
+
+Use the `events` namespace already attached to each model for transient UI
+signals. The model and record choose the authorized sync group; the payload
+does not need routing fields or caller-authored identity.
+
+```tsx
+const ablo = useAblo();
+
+useEffect(() => {
+  if (!ablo) return;
+  return ablo.slideDecks.events.subscribe(deckId, 'cursor', (cursor, context) => {
+    drawRemoteCursor(context.sender.presenceSessionId, cursor);
+  });
+}, [ablo, deckId]);
+
+function onPointerMove(x: number, y: number) {
+  ablo?.slideDecks.events.send(deckId, 'cursor', { slideId, x, y });
+}
+```
+
+The same shape works for code editors:
+
+```ts
+ablo.files.events.send(fileId, 'selection', { anchor, head });
+```
+
+Events are lossy and are not replayed after reconnect, which fits cursor and
+live-selection updates. Ablo enters and leaves the record scope with each
+subscription, routes only inside that scope, and delivers authenticated
+`sender` and `sentAt` context separately from the application payload. Use
+durable model fields when state must survive reconnects. The sending connection
+does not receive its own event. Coalesce or throttle pointer movement in the
+application; model events do not currently declare a per-event `maxHz`.
+
 ## usePeers: read-only presence
 
 `usePeers` reads the presence stream already flowing for the client's scoped

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.61.0",
+  "version": "0.63.0",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -145,8 +145,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "^0.61.0",
-    "@abloatai/transaction": "^0.61.0",
+    "@abloatai/humans": "^0.63.0",
+    "@abloatai/transaction": "^0.63.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {