@abloatai/ablo 0.59.1 → 0.59.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.59.2
+
+### Patch Changes
+
+- Updated dependencies [0b2fff7]
+  - @abloatai/humans@0.59.2
+  - @abloatai/transaction@0.59.2
+
 ## 0.59.1
 
 ### Plans recognize completed database migrations

package/dist/ai-sdk.js.map

@@ -1 +1 @@
-{"version":3,"file":"ai-sdk.js","sourceRoot":"","sources":["../src/ai-sdk.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAE7C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CACnD,CAAC,CAAC;AAYH,kFAAkF;AAClF,MAAM,UAAU,cAAc,CAC5B,KAA2B,EAC3B,UAAwC,EAAE;IAE1C,MAAM,EAAE,OAAO,EAAE,GAAG,2BAA2B,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CACjC,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CACzE,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAC5B,QAAQ,EACR,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,EACjE,CAAC,CACF,CAAC;IACF,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,0DAA0D,OAAO,EAAE;KAC7E,CAAC;AACJ,CAAC"}
+{"version":3,"file":"ai-sdk.js","sourceRoot":"","sources":["../src/ai-sdk.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAE7C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CACnD,CAAC,CAAC;AAYH,kFAAkF;AAClF,MAAM,UAAU,cAAc,CAC5B,KAA2B,EAC3B,OAAO,GAAiC,EAAE;IAE1C,MAAM,EAAE,OAAO,EAAE,GAAG,2BAA2B,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CACjC,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CACzE,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAC5B,QAAQ,EACR,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,EACjE,CAAC,CACF,CAAC;IACF,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,0DAA0D,OAAO,EAAE;KAC7E,CAAC;AACJ,CAAC"}

package/docs/agents.md

@@ -21,16 +21,49 @@ console.log(matching[0].title);
 These are observational reads. Use `read({ id })` only when a later Ablo write
 depends on that exact version and will pass it through `reads`.
 
-An agent is a **reactive** participant: it wakes on something happening, reads
-what it needs, writes a result, and goes idle. That's a request/response
-workload — so agents talk to Ablo over **plain HTTP**, holding no WebSocket. The
-credential *is* the identity; the server resolves the org, scope, and actor from
-the key on every request.
+Most agents wake on a trigger, read what they need, write a result, and go idle.
+That is a request/response workload, so they use plain HTTP. A resident agent
+that needs pushed deltas, queued-claim grants, or presence selects
+`transport: 'websocket'`. The credential is the identity on both carriers; the
+server resolves the org, scope, and actor from it.
 
-Agents get the stateless plane (HTTP). People — when you add the `humans()`
-plugin — get the live plane (WebSocket: presence, optimistic, sub-100ms).
-**Both operate on the same typed, coordinated state — and coordinate *with each
-other*.**
+Short-lived agents use HTTP. Long-running agents may add a multiplexed
+WebSocket without installing the human materializer. People add the `humans()`
+plugin for a local reactive graph. All three operate on the same typed,
+coordinated state and enter the same server-side commit and claim paths.
+
+```ts
+const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+  transport: 'websocket',
+  cursorStore,
+});
+
+await ablo.ready();
+
+for await (const delta of ablo.observe()) {
+  await applyToAgentState(delta);
+  await delta.checkpoint(); // persist the cursor, then acknowledge it
+}
+```
+
+The selected WebSocket is shared by commits, row claims and releases,
+subscription changes, pushed deltas, presence, and collaboration events.
+Reconnect sends the last checkpointed position, so an uncheckpointed delta is
+eligible for redelivery. An unsupported protocol version closes explicitly
+instead of silently falling back to a different wire dialect.
+
+The client retains no delta backlog while `observe()` is inactive. Starting an
+observer requests replay from the durable checkpoint. An active observer has a
+bounded in-memory backlog; if it falls behind that bound, observation fails
+explicitly and can be restarted from the same durable checkpoint.
+
+The public operation names do not change with the carrier. For example,
+`ablo.records.update(...)` and `ablo.records.claim(...)` are the same calls on
+HTTP and WebSocket. HTTP remains available for point reads and administrative
+resources; `context().onChange` uses POST/SSE when HTTP is selected and reuses
+the socket when WebSocket is selected.
 
 <Note>
 Agents transact against your **pushed schema**, same as everyone — `ablo.records`
@@ -62,10 +95,9 @@ await ablo.records.update({ id: record.id, data: { status: "done" } });
 
 It exposes `get` / `list` / `create` / `update` / `delete`, plus `commits`
 and `claim`. It does **not** expose stateful-only `local` reads or model
-`onChange` subscriptions. Those need a WebSocket, so with `transport: 'http'`
-they are compile errors. `context().onChange` is separate: while its listener
-is active, it holds one HTTP response open until the context changes or the
-listener stops.
+`onChange` subscriptions. `context().onChange` is separate: it reuses the
+selected WebSocket transport, or holds one POST/SSE response until the context
+changes on the HTTP transport.
 
 ## Managed scoped agents
 

package/docs/deployment.md

@@ -127,6 +127,7 @@ runs. In production that resolves to four rows:
 |---|---|---|
 | Server, worker, agent, cron | `sk_` in `ABLO_API_KEY` | Defaults from the environment, so most code passes nothing. |
 | Serverless function | `sk_` in `ABLO_API_KEY`, with `transport: 'http'` | Stateless request/response; nothing held open across invocations. |
+| Resident agent | restricted `rk_` or agent-scoped credential, with `transport: 'websocket'` | One multiplexed WebSocket per client and Ablo cell; checkpoint durable deltas before acknowledging. |
 | Browser, read-only | root-bound `pk_` | Publishable, safe to ship, and read-only. |
 | Browser, writing as the signed-in user | `authEndpoint` | A route on your backend mints a short-lived `ek_` per user. |
 

package/docs/options.md

@@ -160,11 +160,13 @@ workflow or deployment lanes.
 
 ## transport
 
-The package-root client uses request/response HTTP. `transport: 'http'` is
-accepted but optional.
+The package-root client defaults to request/response HTTP. Select
+`transport: 'websocket'` for a resident agent that needs pushed coordination;
+the model, commit, claim, and context vocabulary stays unchanged.
 
-Live state, presence, and local reads belong to the reactive client described in
-the [React guide](./react.md), rather than another value on this option.
+Local materialized state and reactive reads still belong to the human client
+described in the [React guide](./react.md); selecting WebSocket here adds a
+carrier, not the human materializer.
 
 ## timeoutMs
 

package/package.json

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