@abloatai/ablo 0.59.2 → 0.60.0

package/docs/react.md

@@ -33,7 +33,7 @@ import { schema } from '@/ablo/schema';
 // from your own server route (see Identity below).
 export const ablo = Ablo({
   schema,
-  authEndpoint: '/api/ablo-session',
+  session: { endpoint: '/api/ablo-session' },
 });
 
 // The typed binding: capture the schema once, and every component imports
@@ -188,52 +188,11 @@ imperative work after an event or effect.
 
 See [API reference](/docs/api) for the full options surface.
 
-## useJoin: scoped presence + read interest
-
-`useJoin` is the React form of `ablo.<model>.join`. It joins multiplayer for a
-scope on the engine's existing socket (one TCP connection, N logical
-sub-syncgroup participants) and returns the reactive participant facade. Use it
-when a mount should both *see* who else is on an entity and, optionally, declare
-write interest in it.
-
-```tsx
-'use client';
-
-import { useJoin } from '@abloatai/ablo/react';
-
-export function CollectionPresence({ workspaceId }: { workspaceId: string }) {
-  const { peers, claims, status } = useJoin({
-    scope: { entryCollections: workspaceId },
-    claim: true,   // I intend to write — pin the scope + let peers observe the claim
-    hydrate: true, // backfill the workspace's current rows if not already loaded
-  });
-
-  if (status !== 'joined') return <span>connecting…</span>;
-  return <span>{peers.length} other{peers.length === 1 ? '' : 's'} here</span>;
-}
-```
-
-Options (`UseJoinOptions`):
-
-| Option | Default | Effect |
-| --- | --- | --- |
-| `scope` |: | Model-form scope (`{ entryCollections: id }`), resolved through the schema. Omit for engine-wide. |
-| `claim` | `false` | Acquire a write-claim on the scope (sent so peers observe it; pins the scope so it never warm-drops while held). A viewer is not a claimant: leave `false` for read-only. |
-| `hydrate` | `false` | Backfill the scope's current rows into the pool once on enter, then keep them fresh via the live tail. Set `true` for deep-linked / never-opened entities. Single-flight; soft-fails. |
-| `ttlSeconds` |: | Lease TTL for the scope claim. |
-| `paused` | `false` | Tear down and don't re-join while true. |
-
-Returns (`UseJoinReturn`): `{ participant, peers, claims, status, error }`.
-`peers` is everyone else on the scope's sync groups; `claims` is their active
-write-claims; `status` is the join lifecycle. Auto-cleans up on unmount or when
-`paused` flips true.
-
 ## usePeers: read-only presence
 
-`usePeers` is a *pure reader* of the presence stream already flowing on the
-connection. Unlike `useJoin`, it does **not** enter/leave a scope (no
-`update_subscription`, no warm-TTL churn) — so reading it never changes what the
-connection is subscribed to.
+`usePeers` reads the presence stream already flowing for the client's scoped
+groups. It does not create a second membership or lease and does not change the
+connection's subscriptions.
 
 ```tsx
 'use client';
@@ -247,15 +206,12 @@ export function CursorBroadcaster({ workspaceId }: { workspaceId: string }) {
 }
 ```
 
-Pass `scope` to narrow to a sync group's peers, or omit it for everyone on the
-engine's groups. Returns `ReadonlyArray<Peer>`, where each `Peer` carries
+Pass a schema-shaped group scope to filter the visible peers, or omit it for
+everyone on the client's groups. Returns `ReadonlyArray<Peer>`, where each `Peer` carries
 `participantKind` (`'user' | 'agent' | 'system'`), `participantId`, optional
 `label`, `syncGroups`, `activity`, `lastActive`, and optional `activeClaims`.
-
-Reach for `usePeers` (not a second `useJoin`) when some **other** mount already
-owns the scope's read interest — scope `leave` is not reference-counted, so a
-second `useJoin` on the same scope would warm-drop the owner's subscription on
-unmount.
+Use `ablo.<model>.claim` when the caller needs exclusion; reading presence does
+not claim anything.
 
 ## Next.js
 

package/docs/security.md

@@ -13,7 +13,7 @@ credential, normally supplied through `ABLO_API_KEY`. Never include it in a
 browser bundle or agent-generated output.
 
 Browsers use either a publishable read-only `pk_` credential or a short-lived,
-scoped session minted by your backend through `authEndpoint`. See [API
+scoped session minted by your backend through `session.endpoint`. See [API
 Keys](./api-keys.md) and [Sessions](./sessions.md) for the credential classes and
 minting flow.
 

package/docs/sessions.md

@@ -7,26 +7,31 @@ hands to one actor — a signed-in **person's browser** or a scoped **agent**. I
 the same primitive in both cases (backend-minted, short-lived, scoped); the only
 difference is the subject and how much authority it carries.
 
-One resource mints both:
+One server-only issuer mints both. It is separate from `Ablo(...)` so the
+participant client keeps every schema model name, including `ablo.sessions`:
 
 ```ts Your backend (sk_)
+import Sessions from '@abloatai/ablo/sessions';
+
+const sessions = Sessions({ schema, apiKey: process.env.ABLO_API_KEY });
+
 // A logged-in person's browser session — only the operations this UI needs.
-const userSession = await ablo.sessions.create({
+const userSession = await sessions.create({
   user: { id: currentUser.id },
   can: { records: ['read', 'update'], workspaces: ['read'] },
 });
 
-// Recommended agent path — returns a ready, scoped client.
-const agent = await ablo.agents.create({
-  name: 'record-writer',
+// An agent session — hand its rk_ to the agent runtime.
+const agentSession = await sessions.create({
+  agent: { id: crypto.randomUUID() },
   can: { records: ['read', 'update'], workspaces: ['read'] },
+  userMeta: { name: 'record-writer' },
 });
 ```
 
-`sessions.create({ user, can })` mints an `ek_` (ephemeral key).
-`agents.create({ can })` mints and manages an `rk_` (restricted key). Use the
-lower-level `sessions.create({ agent, can })` only when another runtime needs
-the raw agent token.
+`sessions.create({ user, can })` mints an `ek_` (ephemeral key), while
+`sessions.create({ agent, can })` mints an `rk_` (restricted key). There is one
+issuance API; the subject selects the credential kind and attribution.
 
 It exists because of one rule: **the browser can never hold a secret.** Your
 `sk_` lives on the server; the browser only ever holds a minted session token
@@ -43,30 +48,39 @@ session token *is* that assertion: "this connection is acting as `U`, in org
 
 ## End-user sessions (`ek_`)
 
-For a logged-in person using your app. Mint on a backend route that has already
-authenticated the user:
+For a logged-in person using your app. Mount a session handler on a backend
+route and connect it to the authentication you already use:
 
 ```ts Your backend route (session-authed)
-import { credentialEndpointSuccessSchema } from '@abloatai/ablo/auth';
-
-const { token, expiresAt } = await ablo.sessions.create({
-  user: { id: currentUser.id },   // who the session acts as
-  can: { records: ['read', 'update'] },
-  // syncGroups: [...],           // optional; defaults to the user's org + user
+import { headers } from 'next/headers';
+import { auth } from '@/lib/auth';
+import { sessions } from '@/ablo/sessions';
+
+export const POST = sessions.handler({
+  async authenticate() {
+    const session = await auth.api.getSession({ headers: await headers() });
+    return session?.user ?? null;
+  },
+  async grant({ principal: user }) {
+    const membership = await findActiveMembership(user.id);
+    if (!membership) return null;
+
+    return {
+      user: { id: user.id },
+      groups: [`workspace:${membership.workspaceId}`],
+      can: { records: ['read', 'update'] },
+    };
+  },
 });
-return Response.json(
-  credentialEndpointSuccessSchema.parse({
-    token,
-    expiresAt,
-    credentialKind: 'ephemeral',
-  }),
-  { headers: { 'Cache-Control': 'no-store' } },
-);
 ```
 
-`can` is required. The mint fails closed when the grant is absent or empty.
+`authenticate` adapts Better Auth (or any other auth system) to an application
+principal. `grant` derives Ablo identity, groups, and permissions server-side.
+Returning `null` from either step fails closed. The handler owns same-origin
+checks, no-store responses, and the credential envelope; the application never
+handles the token. `can` is required and cannot be empty.
 
-Point a browser `Ablo` client's `authEndpoint` at that route, and pass
+Point a browser `Ablo` client's `session.endpoint` at that route, and pass
 the **instance** to [`<AbloProvider>`](/react). The client fetches the token,
 opens the connection, and re-mints before expiry — your app writes no token
 plumbing:
@@ -80,7 +94,7 @@ import { schema } from '@/ablo.schema';
 
 const ablo = Ablo({
   schema,
-  authEndpoint: '/api/ablo-session',
+  session: { endpoint: '/api/ablo-session' },
 });
 
 export function Providers({ children }: { children: React.ReactNode }) {
@@ -92,8 +106,8 @@ The client owns auth, the credential lifecycle, and the connection; the provider
 is only the thin reactive binding over it.
 Build the client **once** at module scope — a new instance per render tears down
 the socket. Need custom headers or a
-body on the exchange? `authEndpoint` also accepts an async resolver that
-returns the token.
+body on the exchange? Pass an async `session` provider that performs the custom
+request and returns its credential response.
 
 ## Agents (`rk_`)
 
@@ -102,47 +116,61 @@ operations. The `can` map is the permission boundary, and it's **typed against
 your schema** — the model keys are your schema's models, so a typo is a compile
 error, not a silent over-grant:
 
+The examples below reuse the server-only `sessions` issuer constructed above.
+
 ```ts
-const agent = await ablo.agents.create({
-  name: 'record-writer',
+const session = await sessions.create({
+  agent: { id: crypto.randomUUID() },
   can: { records: ['update'] },  // typed off the schema — no magic strings
   ttlSeconds: 600,
+  userMeta: { name: 'record-writer' },
 });
 
+const agent = Ablo({ schema, session, transport: 'http' });
 await agent.records.update({ id, data });
 await agent.dispose();
 ```
 
-The returned client refreshes its own short-lived credential. A write grant
-automatically includes the corresponding read, so
+The session is the credential; construct the agent client in the runtime that
+will use it. A write grant automatically includes the corresponding read, so
 `can: { records: ['update'] }` is enforced as `record.update` plus `record.read`.
 Operations are `'read' | 'create' | 'update' | 'delete'`.
 
-For a reusable grant, use TypeScript's `satisfies`. It checks the object against
-the schema while preserving its narrow literals—there is no string parser or
-second permission model:
+Give reusable access a domain name and keep it next to the worker that owns it:
 
 ```ts
-import type { CapabilityGrant } from '@abloatai/ablo/auth';
-import { schema } from './ablo.schema';
-
-const recordWriterCan = {
+const workerAccess = {
   records: ['update'],
-} satisfies CapabilityGrant<typeof schema>;
+} as const;
 
-const agent = await ablo.agents.create({ can: recordWriterCan });
+const session = await sessions.create({
+  agent: { id: crypto.randomUUID() },
+  can: workerAccess,
+});
 ```
 
-`documents` instead of `records`, or `'write'` instead of `'update'`, is a compile
-error. At runtime the SDK parses the same grant with the schema-bound Zod
-contract before minting, and the server validates it again against the active
-pushed schema.
+The SDK checks the model names and operations against the bound schema before
+minting, and the server validates them again against the active pushed schema.
 
-<Note>
-Use `sessions.create({ agent, can })` when a separate runtime, MCP process, or
-protocol integration needs the raw token. For an agent running in the current
-server process, prefer `agents.create({ can })`.
-</Note>
+For a long-running agent, pass an async session provider. It re-mints the same
+logical identity through the canonical resource; the client caches each result
+until it approaches `expiresAt` and uses the replacement for HTTP requests and
+WebSocket reconnects:
+
+```ts
+const session = () => sessions.create({
+  agent: { id: stableWorkerId },
+  can: workerAccess,
+  groups: [workspaceGroup],
+});
+
+const agent = Ablo({ schema, session });
+```
+
+A static `session` resource does not invent authority to renew itself. It lives
+until `expiresAt`; use a provider when the client must outlive that credential.
+Session clients use one reconnecting WebSocket by default. Pass
+`transport: 'http'` only for bounded scoped work that must not hold a socket.
 
 ## Mint
 
@@ -156,41 +184,42 @@ for the actor.
 | `can` | both | Required non-empty per-model operation allowlist, typed off the schema. |
 | `organizationId` | user | Mint into a customer organization instead of the key's own. Requires `organization:act-as`. |
 | `schemaProject` | user | Override the schema project for a cross-org mint. Usually omitted because the owning key's project is the default. |
-| `syncGroups` | both | Narrow the session below its default scope. Omit to inherit. |
+| `groups` | both | Narrow the session below its default scope. Omit to inherit. |
 | `ttlSeconds` | both | Lifetime in seconds. Defaults to `900` (15m). |
 | `userMeta` | both | Opaque identity blob echoed back to the client. |
 
 ## Lifecycle
 
-Sessions are **short-lived by design** (~15 minutes) and, for browsers,
-**auto-refreshed** — the provider re-mints ahead of expiry, so a session never
-drops at the boundary. Signing out stops refresh and the old token expires on
-its own.
+Sessions are **short-lived by design** (~15 minutes). A renewable browser or
+agent provider pre-mints ahead of expiry and reconnects with the replacement,
+so the logical session and durable observation continue even though an
+individual socket may be replaced. A static session ends at its credential's
+expiry. Signing out stops refresh and the old token expires on its own.
 
 Revoke immediately when a token is exposed or an actor loses access:
 
 ```ts
-await ablo.sessions.revoke({ id: session.id });
+await sessions.revoke({ id: session.id });
 ```
 
 Agent sessions can rotate with overlap so a worker can adopt the replacement
 before the previous token expires:
 
 ```ts
-const replacement = await ablo.sessions.rotate({
+const replacement = await sessions.rotate({
   id: session.id,
   graceSeconds: 300,
   ttlSeconds: 900,
 });
 ```
 
-Browser `ek_` sessions rotate through `authEndpoint`; do not distribute rotated
+Browser `ek_` sessions rotate through `session.endpoint`; do not distribute rotated
 browser tokens manually.
 
 ### Offline & sign-out
 
 The short session token is **not** your user's login — it's a minutes-long
-credential layered on top of whatever long-lived auth your `authEndpoint`
+credential layered on top of whatever long-lived auth your `session.endpoint`
 already enforces (your own session cookie, an IdP, etc.). The provider keeps
 those two lifetimes separate, which means:
 
@@ -200,7 +229,7 @@ those two lifetimes separate, which means:
   connectivity or tab focus returns. The user stays signed in for as long as
   your underlying session is valid, however brief or long the network drop.
 - **The user is signed out only when the underlying session is genuinely
-  gone** — your `authEndpoint` responds `401` with the canonical
+  gone** — your session endpoint responds `401` with the canonical
   `{ error: { code: 'session_expired' } }` body. An unrelated `401` or `403`
   is a policy/configuration failure, not proof that the login ended.
 
@@ -209,10 +238,9 @@ rejection of the *long-lived* credential ends the session — a network failure
 never does.
 
 <Note>
-Use `credentialEndpointSuccessSchema` and `credentialEndpointErrorSchema` from
-`@abloatai/ablo/auth` on the route. Return `session_expired` only when the
-application login is actually gone, and let network/`5xx` failures surface as
-errors.
+`sessions.handler` returns `session_expired` only when `authenticate` reports
+that the application login is gone. Exceptions and network failures remain
+transient errors; they do not sign the user out.
 </Note>
 
 ## Scope
@@ -221,7 +249,7 @@ A user session carries the user's **base** sync-groups (`org:`/`user:`/`team:`),
 derived from the identity you minted it for. **Dynamic, relation-driven
 membership** (e.g. a `archive:<id>` the user was just added to) is resolved
 **server-side at connect** and unioned on top — so scope stays live, not frozen
-at mint time. Pass `syncGroups` only when you want to *narrow* below the default.
+at mint time. Pass `groups` only when you want to *narrow* below the default.
 
 ## Your schema, your users (the default)
 
@@ -268,7 +296,7 @@ project while its *data* stays in the customer's own org:
 
 ```ts
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_PLATFORM_KEY });
-const { token } = await ablo.sessions.create({
+const { token } = await sessions.create({
   user: { id: userId },
   organizationId, // DATA → this customer's isolated org
   can: { records: ['read', 'update'] },
@@ -305,5 +333,5 @@ compromise — which is exactly why it never leaves your server.
 |---|---|---|
 | For | a **person** in the browser | an **agent** / automation |
 | Authority | narrow (explicit `can` allowlist) | narrow (explicit `can` allowlist) |
-| Mint | `ablo.sessions.create({ user: { id }, can })` | `ablo.sessions.create({ agent: { id }, can })` |
+| Mint | `sessions.create({ user: { id }, can })` | `sessions.create({ agent: { id }, can })` |
 | Lives where | the user's **browser** | the agent runtime |

package/docs/transports.md

@@ -0,0 +1,124 @@
+# Transports
+
+> Transport follows identity: API-key services use HTTP and scoped sessions use one multiplexed WebSocket.
+
+A session is not a WebSocket. It is the short-lived credential that identifies
+an actor and bounds its authority. `Ablo()` owns the client lifecycle, and the
+credential decides the normal transport; `transport: 'http'` is the explicit
+escape hatch for bounded work that still needs a distinct session identity.
+
+| Workload | Select | Lifetime |
+|---|---|---|
+| API-key route handler, job, cron, or serverless invocation | HTTP (default) | No persistent connection; dispose after bounded work. |
+| Wait for one captured context to become stale | HTTP + `context().onChange` | One POST/SSE response, closed after the first matching change or cancellation. |
+| Scoped user or agent session | WebSocket (default) | One reconnecting connection per client and Ablo cell, held until `dispose()`. |
+| Human reactive interface | `humans()` / React client | One WebSocket owned by the long-lived client instance. |
+
+## API-key services use HTTP
+
+An API key identifies trusted service work, so no session or socket is needed:
+
+```ts
+const worker = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+try {
+  await run(worker);
+} finally {
+  await worker.dispose();
+}
+```
+
+For bounded work that must have a distinct agent identity, create a session and
+explicitly select HTTP:
+
+```ts
+import Sessions from '@abloatai/ablo/sessions';
+
+const sessions = Sessions({ schema, apiKey: process.env.ABLO_API_KEY });
+const session = await sessions.create({
+  agent: { id: runId },
+  can: workerAccess,
+  groups: [workspaceGroup],
+});
+
+const worker = Ablo({ schema, session, transport: 'http' });
+```
+
+Reads and administrative resources remain HTTP even when a session client also
+has a WebSocket. The separate `Sessions(...)` issuer always uses HTTP. The
+public model API does not change with the carrier.
+
+## A session owns one reconnecting WebSocket
+
+Use a session provider when the client must outlive one credential:
+
+```ts
+const session = () => sessions.create({
+  agent: { id: stableWorkerId },
+  can: workerAccess,
+  groups: [workspaceGroup],
+});
+
+const agent = Ablo({
+  schema,
+  session,
+  groups: [workspaceGroup],
+  cursorStore,
+});
+
+await agent.ready();
+try {
+  for await (const delta of agent.observe()) {
+    await apply(delta);
+    await delta.checkpoint();
+  }
+} finally {
+  await agent.dispose();
+}
+```
+
+The provider represents one stable actor and grant. The client caches its
+returned session, pre-mints a replacement before `expiresAt`, uses the newest
+credential for later requests and reconnects, and prevents HTTP bootstrap plus
+WebSocket setup from minting twice. A transient mint failure retries; only a
+provider returning no session ends the logical session. Do not reuse one
+provider across different actors, workspaces, or capability sets.
+
+The socket reconnects after transient disconnects and requests replay from the
+last durably checkpointed cursor. Uncheckpointed deltas may be delivered again.
+An active observer has a bounded backlog and fails explicitly if its consumer
+cannot keep up.
+
+The session survives socket replacement, but socket-bound operations have
+deliberate boundaries:
+
+| State | After reconnect |
+|---|---|
+| Durable observation cursor | Replayed from the last checkpoint; duplicates before the checkpoint are discarded. |
+| Active observer | Continues across a renewable credential expiry or transient socket loss. |
+| Last acknowledged subscription | Restored on the replacement socket. |
+| Presence | Re-announced after the replacement socket opens. |
+| Commit awaiting a receipt | Rejects as `commit_no_result`; Ablo never guesses whether the server accepted it. Retry with the same idempotency key. |
+| Row claim or queued claim | Ends with the socket. Re-read and acquire a fresh claim after reconnecting. |
+
+A static session cannot renew itself. When its bearer expires, the session is
+terminal and operations reject instead of reconnecting forever with the same
+credential.
+
+## Where SSE fits
+
+SSE is not the session transport. On an HTTP client,
+`context().onChange` opens one authenticated POST/SSE request and closes it when
+one captured dependency changes. On a WebSocket client, the same operation
+reuses the existing connection, so a long-running agent does not open a
+side-channel SSE stream.
+
+## Groups are two related boundaries
+
+`sessions.create({ groups })` narrows what the credential may access.
+`Ablo({ session, groups })` selects the initial subset that the
+connection observes. Connection groups can narrow delivery but can never widen
+the session's authority. The wire protocol still calls this field
+`syncGroups`; that name does not escape into the application-facing options.
+
+See [Sessions](./sessions.md) for issuance and renewal, [Agents](./agents.md) for
+worker patterns, and [Options](./options.md) for connection tuning.

package/examples/README.md

@@ -26,6 +26,11 @@ Then:
 - write with `ablo.weatherReports.update`
 - dispose the client when the worker finishes
 
+`terminal-showcase/` is the technical product walkthrough. It
+mints one human and one agent participant, rejects a stale agent write, queues
+the agent behind the human's claim, and prints the durable confirmed commit.
+Nothing in its Ablo path is simulated, and it does not call a model provider.
+
 For read-reason-write work, pass the exact returned rows that informed the
 decision. Their watermarks stay opaque:
 
@@ -66,6 +71,8 @@ root and a bare `quickstart.ts` won't be found.
 ```bash
 cd packages/ablo
 ABLO_API_KEY=sk_... npx tsx examples/quickstart.ts
+npx ablo push --schema examples/terminal-showcase/schema.ts
+ABLO_API_KEY=sk_... npx tsx examples/terminal-showcase/index.ts
 ABLO_API_KEY=sk_... RECORD_ID=record_... npx tsx examples/agent-turn.ts
 ABLO_API_KEY=sk_... JOB_ID=job_... npx tsx examples/expensive-agent-turn.ts
 ABLO_API_KEY=sk_... RECORD_ID=record_... npx tsx examples/stale-context-agent-turn.ts