@abloatai/ablo 0.36.0 → 0.37.0

package/docs/sessions.md

@@ -10,20 +10,23 @@ difference is the subject and how much authority it carries.
 One resource mints both:
 
 ```ts Your backend (sk_)
-// A logged-in person's browser session — full authority within their org.
+// A logged-in person's browser session — only the operations this UI needs.
 const userSession = await ablo.sessions.create({
   user: { id: currentUser.id },
+  can: { tasks: ['read', 'update'], workspaces: ['read'] },
 });
 
-// A scoped agent session — gated to exactly the operations you name.
-const agentSession = await ablo.sessions.create({
-  agent: { id: 'agent:task-writer' },
-  can: { Task: ['read', 'update'], Workspace: ['read'] },
+// Recommended agent path — returns a ready, scoped client.
+const agent = await ablo.agents.create({
+  name: 'task-writer',
+  can: { tasks: ['read', 'update'], workspaces: ['read'] },
 });
 ```
 
-`user` mints an `ek_` (ephemeral key); `agent` mints an `rk_` (restricted key).
-You pass `user` **or** `agent` — never both.
+`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.
 
 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
@@ -45,15 +48,24 @@ For a logged-in person using your app. Mint on a backend route that has already
 authenticated the user:
 
 ```ts Your backend route (session-authed)
-const { token } = await ablo.sessions.create({
+import { credentialEndpointSuccessSchema } from '@abloatai/ablo/auth';
+
+const { token, expiresAt } = await ablo.sessions.create({
   user: { id: currentUser.id },   // who the session acts as
+  can: { tasks: ['read', 'update'] },
   // syncGroups: [...],           // optional; defaults to the user's org + user
 });
-return Response.json({ token });  // return ONLY the token to the browser
+return Response.json(
+  credentialEndpointSuccessSchema.parse({
+    token,
+    expiresAt,
+    credentialKind: 'ephemeral',
+  }),
+  { headers: { 'Cache-Control': 'no-store' } },
+);
 ```
 
-A user session has **full data authority** within its org — no operation
-allowlist. It's the human acting as themselves.
+`can` is required. The mint fails closed when the grant is absent or empty.
 
 Point a browser `Ablo` client's `authEndpoint` at that route, and pass
 the **instance** to [`<AbloProvider>`](/react). The client fetches the token,
@@ -84,7 +96,7 @@ the socket. Need custom headers or a
 body on the exchange? `authEndpoint` also accepts an async resolver that
 returns the token.
 
-## Agent sessions (`rk_`)
+## Agents (`rk_`)
 
 For a non-human actor — an agent or automation that should only do **specific**
 operations. The `can` map is the permission boundary, and it's **typed against
@@ -92,23 +104,45 @@ your schema** — the model keys are your schema's models, so a typo is a compil
 error, not a silent over-grant:
 
 ```ts
-const session = await ablo.sessions.create({
-  agent: { id: 'agent:task-writer' },
-  can: { Task: ['read', 'update'] },  // typed off the schema — no magic strings
+const agent = await ablo.agents.create({
+  name: 'task-writer',
+  can: { tasks: ['update'] },  // typed off the schema — no magic strings
   ttlSeconds: 600,
 });
 
-const agent = Ablo({ schema, apiKey: session.token }); // the agent's scoped client
+await agent.tasks.update({ id, data });
+await agent.dispose();
 ```
 
-`can: { Task: ['update'] }` serializes to the wire allowlist `task.update`; the
-server rejects any commit whose operation isn't listed. Operations are
-`'read' | 'create' | 'update' | 'delete'`.
+The returned client refreshes its own short-lived credential. A write grant
+automatically includes the corresponding read, so
+`can: { tasks: ['update'] }` is enforced as `task.update` plus `task.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:
+
+```ts
+import type { CapabilityGrant } from '@abloatai/ablo/auth';
+import { schema } from './ablo.schema';
+
+const taskWriterCan = {
+  tasks: ['update'],
+} satisfies CapabilityGrant<typeof schema>;
+
+const agent = await ablo.agents.create({ can: taskWriterCan });
+```
+
+`documents` instead of `tasks`, 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.
 
 <Note>
-Use `sessions.create({ agent })` to mint a scoped agent credential, then write
-with `ablo.<model>.update(...)` / `ablo.commits.create(...)` under a `claim`.
-This is the path for custom runtimes, MCP sessions, and protocol-level integrations.
+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>
 
 ## Mint
@@ -120,7 +154,7 @@ for the actor.
 | Param | For | Meaning |
 |---|---|---|
 | `user` / `agent` | both | The actor. `id` becomes the token's `participantId`. Pass exactly one. |
-| `can` | agent | Per-model operation allowlist, typed off the schema. |
+| `can` | both | Required non-empty per-model operation allowlist, typed off the schema. |
 | `syncGroups` | 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. |
@@ -129,8 +163,28 @@ for the actor.
 
 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. A revoked or signed-out actor simply stops getting a fresh
-token; the old one expires on its own. There's nothing to revoke by hand.
+drops at the boundary. 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 });
+```
+
+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({
+  id: session.id,
+  graceSeconds: 300,
+  ttlSeconds: 900,
+});
+```
+
+Browser `ek_` sessions rotate through `authEndpoint`; do not distribute rotated
+browser tokens manually.
 
 ### Offline & sign-out
 
@@ -145,20 +199,19 @@ 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
-  rejected** — i.e. your `authEndpoint` responds **`401`/`403`** because the
-  cookie (or IdP session) is missing, expired, or revoked. That's the one
-  signal the provider treats as terminal.
+  gone** — your `authEndpoint` 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.
 
 This mirrors the OAuth refresh-token rule (Okta/Auth0/Authgear): only a
 rejection of the *long-lived* credential ends the session — a network failure
 never does.
 
 <Note>
-Your `authEndpoint` contract follows from this: return the token on success,
-respond **`401`/`403`** only when the user's session is actually gone, and let
-network/`5xx` failures surface as errors. Don't collapse "can't reach the mint
-endpoint" into "session expired" — returning a `401` for a transient blip will
-bounce a still-valid user to your sign-in page.
+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.
 </Note>
 
 ## Scope
@@ -175,8 +228,8 @@ Your schema lives in a **project** — you push it once (`npx ablo push`) and ev
 session you mint resolves against it. The flow for serving end-users:
 
 1. **Push your schema** to your project.
-2. **Mint an `ek_` per user:** `sessions.create({ user: { id } })`. Your users
-   commit to that one schema.
+2. **Mint an `ek_` per user:** `sessions.create({ user: { id }, can })`. Your
+   users commit to that one schema with only the operations in `can`.
 
 **Your users do not have Ablo accounts.** You authenticate them however you
 already do; your server's `sk_` mints the `ek_`. By default the session lands in
@@ -205,6 +258,7 @@ const { token } = await mintUserSessionKey({
     organizationId: schemaOwnerOrgId,
     projectId: schemaProjectId,
   },
+  operations: ['task.read', 'task.update'],
   ttlSeconds: 3600,
 });
 ```
@@ -234,6 +288,6 @@ compromise — which is exactly why it never leaves your server.
 | | User session (`ek_`) | Agent session (`rk_`) |
 |---|---|---|
 | For | a **person** in the browser | an **agent** / automation |
-| Authority | full, within their org | narrow (explicit `can` allowlist) |
-| Mint | `ablo.sessions.create({ user: { id } })` | `ablo.sessions.create({ agent: { id }, can })` |
+| Authority | narrow (explicit `can` allowlist) | narrow (explicit `can` allowlist) |
+| Mint | `ablo.sessions.create({ user: { id }, can })` | `ablo.sessions.create({ agent: { id }, can })` |
 | Lives where | the user's **browser** | the agent runtime |

package/examples/README.md

@@ -37,7 +37,7 @@ no `package.json`, so Node resolves the entry path against the package
 root and a bare `quickstart.ts` won't be found.
 
 ```bash
-cd packages/sync-engine
+cd packages/ablo
 ABLO_API_KEY=sk_test_... npx tsx examples/quickstart.ts
 ```
 
@@ -50,7 +50,7 @@ orchestrator drives the customer handler in-process so signer and
 verifier exchange real signed bytes without leaving the process.
 
 ```bash
-cd packages/sync-engine
+cd packages/ablo
 npx tsx examples/data-source/run.ts
 ```
 

package/examples/data-source/README.md

@@ -16,7 +16,7 @@ when they want Ablo to coordinate writes against rows stored in
 ## Run
 
 ```bash
-cd packages/sync-engine
+cd packages/ablo
 npx tsx examples/data-source/run.ts
 ```
 

package/examples/data-source/ablo-driver.ts

@@ -19,7 +19,7 @@
 import {
   signAbloSourceRequest,
   type Ablo,
-} from '@abloatai/ablo';
+} from '@ablo/ablo';
 
 export interface AbloDriverOptions {
   /**

package/examples/data-source/customer-server.ts

@@ -15,7 +15,7 @@
  * inside a transaction. The shape of the handlers stays identical.
  */
 
-import Ablo, { dataSource, sourceEventForOperation } from '@abloatai/ablo';
+import Ablo, { dataSource, sourceEventForOperation } from '@ablo/ablo';
 import { schema } from './schema';
 
 type TaskRow = {

package/examples/data-source/run.ts

@@ -4,7 +4,7 @@
  * Run (from the package root — the examples/ folder has no package.json
  * of its own, so Node resolves module paths against the package root):
  *
- *   cd packages/sync-engine
+ *   cd packages/ablo
  *   npx tsx examples/data-source/run.ts
  *
  * What this proves:

package/examples/data-source/schema.ts

@@ -12,7 +12,7 @@
  * side without the other is a compile error.
  */
 
-import { defineSchema, model, z } from '@abloatai/ablo/schema';
+import { defineSchema, model, z } from '@ablo/ablo/schema';
 
 export const schema = defineSchema({
   tasks: model({

package/examples/quickstart.ts

@@ -6,8 +6,8 @@
  *   ABLO_API_KEY=sk_test_... npx tsx examples/quickstart.ts
  */
 
-import Ablo from '@abloatai/ablo';
-import { defineSchema, model, z } from '@abloatai/ablo/schema';
+import Ablo from '@ablo/ablo';
+import { defineSchema, model, z } from '@ablo/ablo/schema';
 
 const schema = defineSchema({
   weatherReports: model({

package/llms.txt

@@ -12,7 +12,7 @@ Every surface reaches the same coordinated state. They are not interchangeable.
 
 - SDK, `@abloatai/ablo` with `transport: 'http'` — THE AGENTS THEMSELVES. Stateless, request/response, nothing held open; the credential is the identity. This is the main path — default to it.
 - Coordination MCP, `@abloatai/mcp` — an agent living inside an MCP host (Claude, Cursor). Two jobs: MANAGING your Ablo the way the CLI does (`get_schema`, `list_projects`, `create_project`, `tail_logs`, `get_usage`), and claim/commit as tools over your rows. Call `get_schema` first — it is the only way to learn the model names every data tool needs. `init`, `push`, `pull`, `generate` have no tools (they touch your repo); run those in a shell.
-- `humans()` with `@abloatai/ablo/react` — the interfaces a person watches agent work arrive in. The bare client is the coordination layer (commit, read, observe, claim); `humans()` is the PLUGIN that adds the local watchable copy, live queries, and presence. It `requires: { duplex: true }`, so a `transport: 'http'` agent is rejected at construction rather than left holding a subscription that never delivers. It is installed by default on a socket client with no `plugins` list. There is no `agents()` plugin — agents are the default caller, not a special one. A browser NEVER receives the secret key; mint a session token.
+- `humans()` with `@abloatai/humans/react` — the interfaces a person watches agent work arrive in. The bare client is the coordination layer (commit, read, observe, claim); `humans()` is the plugin that adds the local watchable copy, live queries, and presence. It `requires: { duplex: true }`, so a `transport: 'http'` agent is rejected at construction rather than left holding a subscription that never delivers. It remains the compatibility default for omitted `plugins`; new code should install it explicitly from `@abloatai/humans`. There is no `agents()` plugin — agents are the default caller, not a special one. A browser NEVER receives the secret key; mint a session token.
 - CLI, `ablo` — scaffolding, schema push, connecting a database. Terminals and CI. Agents must run it non-interactively (see the CLI section below).
 - REST, `/api/v1` — runtimes with no SDK.
 - Integration-helper MCP, hosted `/api/mcp` — teaching a coding assistant the SDK WHILE BUILDING an integration. Docs, schema lint, and scaffolds only; it has NO per-model data tools and cannot touch application rows.
@@ -50,7 +50,7 @@ const schema = defineSchema({
 
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
-const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
+const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
 if (!report) throw new Error('Row not found');
 
 // Claim the row (waits if someone else holds it), read the fresh copy off
@@ -74,9 +74,9 @@ For full integrations, use `integration-guide` as the canonical doc. It covers
 the same model API across your own Data Source-backed app databases,
 React selectors, multiplayer, and future agent workers.
 
-Reads come in two flavors, and you pick by whether you can wait. `retrieve({ id })`
+Reads come in two flavors, and you pick by whether you can wait. `get({ id })`
 (one row) and `list({ where })` (many) are async — they answer from the local
-graph and fall back to the server, so await them. `local.retrieve(id)`,
+graph and fall back to the server, so await them. `local.get(id)`,
 `local.list({ where })`, and `local.count({ where })` are the same reads narrowed
 to what has already synced: nothing to await, reactive in render. There is no
 second verb to learn — `local.` is the only difference. The query reads accept
@@ -88,7 +88,7 @@ Workers import the same app schema and select `transport: 'http'`. The transport
 changes; the typed `ablo.<model>` contract does not. There is no public
 schema-less or string-keyed model client.
 
-React reads should use selector `useAblo`: `useAblo((ablo) => ablo.weatherReports.local.retrieve(id))` (synchronous local read, reactive in render).
+React reads should use selector `useAblo`: `useAblo((ablo) => ablo.weatherReports.local.get(id))` (synchronous local read, reactive in render).
 Use zero-argument `useAblo()` only when a component needs the client for an
 event handler or effect. The selector form above is the complete reactive
 surface — every read goes through it.
@@ -117,7 +117,7 @@ A change to one row reaches other rows three ways. ROUTING: a write fans out to
 ## Claimed Behavior
 
 Reads never silently block. Schema reads stay open while a row is claimed.
-Typed reads through `ablo.<model>.retrieve({ id })` return the row by default,
+Typed reads through `ablo.<model>.get({ id })` return the row by default,
 even while it is claimed. Pass `ifClaimed: 'fail'` to throw
 `AbloClaimedError`, and inspect active coordination separately through
 `ablo.<model>.claim.state({ id })`.
@@ -205,10 +205,10 @@ Going live is three things, each done with a `sk_live_` key: register the produc
 
 Import from these public paths only:
 
-- `@abloatai/ablo` — `Ablo`, errors, typed model clients, claims, and `dataSource`.
+- `@abloatai/ablo` — headless HTTP `Ablo`, errors, typed model clients, claims, durable observation, and `dataSource`.
+- `@abloatai/ablo/client` — reactive WebSocket client, presence, and the human-facing materializer.
 - `@abloatai/ablo/schema` — schema DSL.
 - `@abloatai/ablo/react` — React provider and hooks.
-- `@abloatai/ablo/testing` — test harnesses and mocks.
 - `@abloatai/ablo/source` — `dataSource`, the `DataSourceAdapter` spine, `prismaDataSource`. For a customer-canonical Data Source endpoint.
 - `@abloatai/ablo/source/next` — `dataSourceNext` (Next.js App Router `{ POST }`).
 - `@abloatai/ablo/source/drizzle` — `drizzleDataSource`.