@abloatai/ablo 0.34.1 → 0.36.0

package/docs/examples/ai-sdk-tool.md

@@ -1,87 +1,112 @@
 # AI SDK Tool
 
-When an AI agent updates a shared record from inside a tool call, you have a concurrency problem: another agent or a user might be editing the same row, and a naive write silently overwrites their change. This example shows the safe pattern — read the record, claim the row so anyone else waits their turn, write through a version-checked update, and release the claim automatically.
+> Put a claim-and-commit loop inside an AI SDK tool call.
 
-Claims don't lock. If another writer holds the row, `claim` waits for them, re-reads the fresh row, then hands it to you — so two writers serialize instead of clobbering.
+Use AI SDK for the agent loop and Ablo for the state boundary inside the tool.
+When an agent updates a shared record from inside a tool call you have a
+concurrency problem: another agent may be editing the same row, and a naive write
+silently overwrites it. This is the safe pattern — read the record, claim the row
+so anyone else waits their turn, write through a checked update, and release the
+claim automatically.
+
+Claims don't lock. If another writer holds the row, `claim` waits for them,
+re-reads the fresh row, then hands it to you — so two writers serialize instead
+of clobbering.
 
 ```ts
+// app/api/chat/route.ts
 import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z as schemaZ } from '@abloatai/ablo/schema';
 import { anthropic } from '@ai-sdk/anthropic';
-import { convertToModelMessages, streamText, tool, type UIMessage } from 'ai';
+import {
+  streamText,
+  tool,
+  convertToModelMessages,
+  stepCountIs,
+  type UIMessage,
+} from 'ai';
 import { z } from 'zod';
 
+export const runtime = 'nodejs';
+
 const schema = defineSchema({
-  weatherReports: model({
-    location: schemaZ.string(),
-    status: schemaZ.enum(['pending', 'ready']),
-    forecast: schemaZ.string().optional(),
+  tasks: model({
+    title: schemaZ.string(),
+    status: schemaZ.enum(['todo', 'doing', 'done']),
+    summary: schemaZ.string().optional(),
   }),
 });
 
 const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY,
+  transport: 'http',
 });
 
-const updateReport = tool({
-  description: 'Update a weather report in the product database.',
+const updateTask = tool({
+  description: 'Update a task in the product database.',
   inputSchema: z.object({
-    reportId: z.string(),
-    status: z.enum(['pending', 'ready']).optional(),
-    forecast: z.string().optional(),
+    taskId: z.string(),
+    status: z.enum(['todo', 'doing', 'done']).optional(),
+    summary: z.string().optional(),
   }),
-  execute: async ({ reportId, status, forecast }) => {
+  execute: async ({ taskId, status, summary }) => {
     await ablo.ready();
 
     // retrieve hits the server for the latest row (async — await it).
-    const report = await ablo.weatherReports.retrieve({ id: reportId });
-    if (!report) return { ok: false, reason: 'not_found' };
-
-    // If another agent or user already holds this row, claim waits for them
-    // to finish, re-reads the fresh row, then hands it back on `claim.data`.
-    // The claim is released automatically when it goes out of scope.
-    await using claim = await ablo.weatherReports.claim({
-      id: reportId,
+    const task = await ablo.tasks.retrieve({ id: taskId });
+    if (!task) return { ok: false, reason: 'not_found' };
+
+    // If another agent already holds this row, claim waits for them to finish,
+    // re-reads the fresh row, then hands it back on `claim.data`. The claim is
+    // released automatically when it goes out of scope.
+    await using claim = await ablo.tasks.claim({
+      id: taskId,
       description: 'editing',
       ttl: '2m',
     });
-    const claimed = claim.data;
 
-    // Because you hold the claim, this update is rejected if the row
-    // changed underneath you, instead of silently overwriting it.
-    const updated = await ablo.weatherReports.update({
-      id: claimed.id,
+    // Because you hold the claim, this update is rejected if the row changed
+    // underneath you, instead of silently overwriting it.
+    const updated = await ablo.tasks.update({
+      id: claim.data.id,
       data: {
-        status: status ?? claimed.status,
-        forecast: forecast ?? claimed.forecast,
+        status: status ?? claim.data.status,
+        summary: summary ?? claim.data.summary,
       },
+      wait: 'confirmed',
     });
 
-    return { ok: true, report: updated };
+    return { ok: true, task: updated };
   },
 });
 
 export async function POST(req: Request) {
-  // `useChat` posts UIMessage[]; the model is a server-bound provider instance,
-  // never read off the request body.
+  // useChat sends UIMessage[]; convert before handing to the model.
   const { messages }: { messages: UIMessage[] } = await req.json();
 
-  return streamText({
-    model: anthropic('claude-sonnet-4-6'),
+  const result = streamText({
+    // The model is a SERVER-bound provider instance — never sent from the client.
+    model: anthropic('claude-sonnet-5'),
     messages: await convertToModelMessages(messages),
-    tools: { updateReport },
-  }).toUIMessageStreamResponse();
+    tools: { updateTask },
+    stopWhen: stepCountIs(5),
+    maxOutputTokens: 2048,
+  });
+
+  return result.toUIMessageStreamResponse();
 }
 ```
 
 The model provider is interchangeable — swap `anthropic(...)` for any
-server-bound provider instance. What matters is that the route binds the model
-on the server (never trusting one sent in the request body), converts the
-incoming `UIMessage[]` with `convertToModelMessages`, and that the tool:
-
-- reads the latest weather report with `retrieve` (a server read),
-- claims the row — if someone else holds it, the claim waits for them, then re-reads,
-- writes through `update`, which is rejected if the row changed underneath you,
-- releases the claim automatically when the handle goes out of scope,
-- waits for server confirmation.
+server-bound provider instance. What matters is that the route binds the model on
+the server (never trusting one sent in the request body), converts the incoming
+`UIMessage[]` with `convertToModelMessages`, and that the tool:
+
+- reads the latest row with `retrieve` (a server read),
+- claims it for exclusive, ordered access — if someone else holds it, the claim
+  waits for them, then re-reads,
+- writes through the model resource, which is rejected if the row changed
+  underneath you,
+- waits for confirmation with `wait: 'confirmed'`,
+- and auto-releases the claim when the tool returns.

package/docs/examples/existing-python-backend.md

@@ -1,10 +1,12 @@
 # Existing Python Backend
 
-Put Ablo in front of the records several people (or AI agents) edit at once and
-you get two things at no cost to your stack: every edit fans out live to
-everyone watching, and humans and agents write through one shared contract. Your
-Python service and database stay the source of truth — Ablo doesn't replace your
-backend, it coordinates the writes into it. You stop calling your endpoint
+> Add agent coordination to a Python API server without replacing it.
+
+Put Ablo in front of the records several agents (or the people alongside them)
+edit at once and you get two things at no cost to your stack: every edit fans out
+live to everyone watching, and agents and people write through one shared
+contract. The goal is not to replace the backend — your Python service and
+database stay the source of truth, and Ablo coordinates the writes into them. You stop calling your endpoint
 directly; you call Ablo, Ablo calls your endpoint, and Ablo pushes the result
 back out to every browser and agent on that record.
 
@@ -110,7 +112,7 @@ export function ReportRow({
 }: {
   report: { id: string; location: string; status: string };
 }) {
-  const report = useAblo((ablo) => ablo.weatherReports.get(serverReport.id)) ?? serverReport;
+  const report = useAblo((ablo) => ablo.weatherReports.local.retrieve(serverReport.id)) ?? serverReport;
   const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));
   const claimed = Boolean(active);
 

package/docs/examples/nextjs.md

@@ -1,80 +1,163 @@
 # Next.js Example
 
-Building collaborative state in a Next.js app means handling three things at
-once: a fast initial render from the server, writes that don't overwrite a
-teammate's change, and a UI that updates the moment data changes. This example
-wires all three with Ablo Sync. The key piece is `claim()` — commit a write
-through it and Ablo rejects the write if someone edited the same record since
-you read it, so you never silently clobber another person's work.
+> App-router setup: the two clients, the session route, and reactive reads.
 
-Claims don't lock. If another writer holds the row, `claim` waits for them,
-re-reads the fresh row, then hands it to you — so two writers serialize instead
-of clobbering.
+A production-shaped Next.js app on Ablo — App Router, Server Actions, React
+Server Components, and live client subscriptions. It handles three things at
+once: a fast initial render from the server, writes that don't overwrite work
+already in progress, and a UI that updates the moment data changes.
 
-The app uses three layers, mapped to three files: a React Server Component reads
-and renders, a Server Action claims and writes, and a client component shows
-live updates.
+The key piece is `claim()`. Commit a write through it and Ablo rejects the write
+if the record moved since you read it, so nothing is silently clobbered. Claims
+don't lock: if another writer holds the row, `claim` waits for them, re-reads the
+fresh row, then hands it to you — writers serialize instead of colliding.
 
 ## Structure
 
 ```txt
 app/
-  reports/
+  layout.tsx                # wraps the tree in <Providers>
+  providers.tsx             # Client: browser Ablo client + <AbloProvider>
+  api/
+    ablo-session/
+      route.ts              # mints a per-user ek_ token for the browser
+  tasks/
     [id]/
-      page.tsx          # RSC: retrieve + render
-      actions.ts        # Server Action: write that's rejected if someone else edited first
-      ReportEditor.tsx    # Client: live updates
-  lib/
-    ablo.ts             # Schema-backed Ablo client for server actions
+      page.tsx              # RSC: retrieve + render
+      actions.ts            # Server Action: claim, then write
+      TaskEditor.tsx        # Client: live updates
+lib/
+  ablo.ts                   # Server Ablo client (holds ABLO_API_KEY)
+  ablo.schema.ts            # shared schema
+```
+
+There are **two** Ablo clients, and the split is the whole point:
+
+- **Server** (`lib/ablo.ts`) holds the secret `apiKey` (`sk_`). Used by RSCs,
+  Server Actions, and route handlers. Never imported into a client component.
+- **Browser** (`app/providers.tsx`) holds **no secret**. It fetches a
+  short-lived per-user token (`ek_`) from a backend route via `authEndpoint`.
+
+Skipping the browser half is the most common setup mistake — the client then
+has no credential and the engine fails to initialize with `session_expired`.
+
+## Server Client
+
+```ts
+// lib/ablo.ts — server-only
+import Ablo from '@abloatai/ablo';
+import { schema } from './ablo.schema';
+
+export const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+  transport: 'http',
+});
+```
+
+## Session Route
+
+The browser can't hold `sk_`, so a backend route mints a scoped, short-lived
+`ek_` for the signed-in user. Guard it with your own auth.
+
+```ts
+// app/api/ablo-session/route.ts
+import { ablo } from '@/lib/ablo';
+import { getCurrentUser } from '@/auth';
+
+export async function POST() {
+  const user = await getCurrentUser();
+  if (!user) return new Response('Unauthorized', { status: 401 });
+
+  const session = await ablo.sessions.create({ user: { id: user.id } });
+  return Response.json({ token: session.token });
+}
+```
+
+## Provider
+
+The browser client points `authEndpoint` at that route and is handed to
+`<AbloProvider>` as an instance. Build it once at module scope so the socket
+isn't torn down on every render.
+
+```tsx
+// app/providers.tsx
+'use client';
+
+import Ablo from '@abloatai/ablo';
+import { AbloProvider } from '@abloatai/ablo/react';
+import { schema } from '@/lib/ablo.schema';
+
+const ablo = Ablo({
+  schema,
+  authEndpoint: '/api/ablo-session',
+});
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <AbloProvider client={ablo}>{children}</AbloProvider>;
+}
+```
+
+```tsx
+// app/layout.tsx
+import { Providers } from './providers';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
 ```
 
 ## RSC Initial Render
 
 ```tsx
-// app/reports/[id]/page.tsx
+// app/tasks/[id]/page.tsx
 import { ablo } from '@/lib/ablo';
 
-export default async function ReportPage({
+export default async function TaskPage({
   params,
 }: { params: Promise<{ id: string }> }) {
   const { id } = await params;
   await ablo.ready();
-  const report = await ablo.weatherReports.retrieve({ id });
-  if (!report) return null;
+  const task = await ablo.tasks.retrieve({ id });
+  if (!task) return null;
 
-  return <ReportEditor report={report} />;
+  return <TaskEditor task={task} />;
 }
 ```
 
 ## Server Action Commit
 
 ```ts
-// app/reports/[id]/actions.ts
+// app/tasks/[id]/actions.ts
 'use server';
 
 import { ablo } from '@/lib/ablo';
 
-export async function markReady(id: string) {
-  await using claim = await ablo.weatherReports.claim({
-    id,
-    queue: false,
-    description: 'marking_ready',
-  });
-  const claimed = claim.data;
+export async function markDone(id: string) {
+  // Claim grants exclusive, ordered access and hands back the fresh row.
+  await using claim = await ablo.tasks.claim({ id });
 
-  const report = await ablo.weatherReports.update({
-    id: claimed.id,
-    data: { status: 'ready' },
+  const task = await ablo.tasks.update({
+    id,
+    data: { status: 'done' },
+    claim,
     wait: 'confirmed',
   });
 
-  return { status: 'ready', report };
+  return { status: 'done', task };
+  // claim auto-releases as the action returns
 }
 ```
 
-The write runs while the `claim` is held. If another participant commits
-between the read and the write, the commit is rejected because the row changed
-underneath you. The action can re-fetch and ask the user to retry.
+The write runs while the claim is held. If anything else commits between the
+read and the write, the commit is rejected because the row changed underneath
+you — re-fetch and retry.
 
 ## Live Client
 
@@ -83,14 +166,14 @@ underneath you. The action can re-fetch and ask the user to retry.
 
 import { useAblo } from '@abloatai/ablo/react';
 
-export function ReportEditor({ report: serverReport }: Props) {
-  const data = useAblo((ablo) => ablo.weatherReports.get(serverReport.id)) ?? serverReport;
-  const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));
-  const claimed = Boolean(active);
+export function TaskEditor({ task: serverTask }: Props) {
+  const data = useAblo((ablo) => ablo.tasks.local.retrieve(serverTask.id)) ?? serverTask;
+  const holder = useAblo((ablo) => ablo.tasks.claim.state({ id: serverTask.id }));
+  const busy = Boolean(holder);
 
   return (
-    <button disabled={claimed || data.status === 'ready'}>
-      {claimed ? 'Someone is editing' : 'Mark ready'}
+    <button disabled={busy || data.status === 'done'}>
+      {busy ? 'Someone is editing' : 'Mark done'}
     </button>
   );
 }
@@ -98,6 +181,5 @@ export function ReportEditor({ report: serverReport }: Props) {
 
 ## More
 
-- [Next.js landing](/nextjs) — the product overview.
-- [React reference](/docs/react) — every option on `useAblo`.
-- [API reference](/docs/api) — every option on the write path.
+- [React reference](../react.md) — every option on `useAblo`.
+- [API reference](../api.md) — every option on the write path.

package/docs/examples/scoped-agent.md

@@ -1,40 +1,41 @@
-# Agent Scoped to One Deck
+# Agent Scoped to One Workspace
 
-You want an agent that edits **one deck** and pushes realtime updates to the
-people on **that deck only** — not a broadcast to the whole org. The catch most
-people hit: which write reaches whom is decided by how the rows *relate*, not by
-which columns the write touched. So a slide edit that never sets `deckId` still
-reaches everyone viewing the deck, because the slide already belongs to it. You
-get this by declaring the relationship once, then narrowing the agent to the deck
-id — you never assemble a `deck:<id>` audience string by hand.
+> Narrow an agent to a single record's audience, so its writes reach that group and no one else.
+
+You want an agent that edits **one workspace** and pushes realtime updates to the
+participants on **that workspace only** — not a broadcast to the whole org. The
+catch most people hit: which write reaches whom is decided by how the rows
+*relate*, not by which columns the write touched. So a task edit that never sets
+`workspaceId` still reaches everyone watching the workspace, because the task already
+belongs to it. You get this by declaring the relationship once, then narrowing the
+agent to the workspace id — you never assemble a `workspace:<id>` audience string by
+hand.
 
 The three steps below show how to declare it, scope the agent, and write.
 
 See [Identity & Sync Groups](../identity.md) for the full reference.
 
-## 1. Schema — declare the relationship, once
+## 1. Schema: declare the relationship, once
 
 ```ts
 import { defineSchema, identityRole, model, relation, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema(
   {
-    // A deck's rows form the group `deck:<id>` (the kind comes from `groups.root`).
-    decks: model(
+    // A workspace's rows form the group `workspace:<id>` (the kind comes from `groups.root`).
+    workspaces: model(
       { title: z.string() },
-      {},
-      { groups: { root: 'deck' } },
+      { groups: { root: 'workspace' } },
     ),
-    // A slide has no group of its own. It inherits its deck's group via the
-    // `parent` edge, so a slide write reaches everyone viewing the deck.
-    slides: model(
-      { deckId: z.string(), body: z.string() },
-      { deck: relation.belongsTo('decks', 'deckId', { parent: true }) },
-      {},
+    // A task has no group of its own. It inherits its workspace's group via the
+    // `parent` edge, so a task write reaches everyone watching the workspace.
+    tasks: model(
+      { workspaceId: z.string(), title: z.string() },
+      { relations: { workspace: relation.belongsTo('workspaces', 'workspaceId', { parent: true }) } },
     ),
   },
   {
-    // Humans get their full org scope automatically from these.
+    // People get their full org scope automatically from these.
     identityRoles: [
       identityRole({ kind: 'org', source: 'organizationId' }),
       identityRole({ kind: 'user', source: 'userId' }),
@@ -43,31 +44,31 @@ export const schema = defineSchema(
 );
 ```
 
-## 2. Dispatch — narrow the agent to the deck it's working on
+## 2. Dispatch: narrow the agent to the workspace it's working on
 
 An agent can never reach more than the user who triggered it — that's the upper
-limit. From there you narrow it to a single deck by minting the agent's session
-against **just that deck's sync group**. You build the group from the **model
-kind and id** with the typed `syncGroup` helper — `syncGroup('deck', deckId)`,
-never a hand-assembled `deck:<id>` string — where `'deck'` is the kind declared
-by the `decks` model's `scope`.
+limit. From there you narrow it to a single workspace by minting the agent's session
+against **just that workspace's sync group**. You build the group from the **model
+kind and id** with the typed `syncGroup` helper — `syncGroup('workspace', workspaceId)`,
+never a hand-assembled `workspace:<id>` string — where `'workspace'` is the kind
+declared by the `workspaces` model's `groups.root`.
 
 Mint the scoped session on your backend (it holds the `sk_` key; the browser
 never does), then hand the short-lived token to the browser client:
 
 ```ts
-// server — mints a scoped agent session for one deck
+// server — mints a scoped agent session for one workspace
 import Ablo from '@abloatai/ablo';
 import { syncGroup } from '@abloatai/ablo/schema';
 import { schema } from './schema';
 
 const server = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
-export async function mintDeckAgentSession(deckId: string, agentId: string) {
+export async function mintProjectAgentSession(workspaceId: string, agentId: string) {
   const { token } = await server.sessions.create({
     agent: { id: agentId },
-    can: { slides: ['read', 'update'] }, // operation allowlist for this run
-    syncGroups: [syncGroup('deck', deckId)], // narrowed to just this deck
+    can: { tasks: ['read', 'update'] }, // operation allowlist for this run
+    syncGroups: [syncGroup('workspace', workspaceId)], // narrowed to just this workspace
   });
   return token;
 }
@@ -81,7 +82,7 @@ import { schema } from './schema';
 
 const ablo = Ablo({
   schema,
-  apiKey: async () => mintDeckAgentSession(deckId, agentId),
+  apiKey: async () => mintProjectAgentSession(workspaceId, agentId),
 });
 
 // The agent run is mounted on behalf of its triggering user.
@@ -91,30 +92,30 @@ const ablo = Ablo({
 ```
 
 `syncGroups` requests, it never grants: at connect the server intersects the
-groups the session asks for with the groups the identity is actually allowed,
-so the agent can never reach a deck its triggering user couldn't.
+groups the session asks for with the groups the identity is actually allowed, so
+the agent can never reach a workspace its triggering user couldn't.
 
-## 3. Write — it fans out to everyone on that deck
+## 3. Write: it fans out to everyone on that workspace
 
 Inside any component under the provider, grab the scoped client with `useAblo()`
-and write. The connection is already narrowed to `deck:<deckId>` from Step 2.
+and write. The connection is already narrowed to `workspace:<workspaceId>` from Step 2.
 
 ```ts
-const ablo = useAblo<(typeof schema)['models']>();
+const ablo = useAblo();
 
-// Other participants subscribed to deck:<deckId> — the human in the editor,
-// a reviewer agent — receive this delta in realtime. Participants on other
-// decks never see it.
-await ablo.slides.update({ id: slideId, data: { body: 'Q4 revenue up 12% YoY' } });
+// Other participants subscribed to workspace:<workspaceId> — a reviewer agent, a
+// person watching in the UI — receive this delta in realtime. Participants on
+// other workspaces never see it.
+await ablo.tasks.update({ id: taskId, data: { title: 'Ship the Q4 report' } });
 ```
 
-The slide's delta is stamped `deck:<deckId>`, derived server-side from the
-slide → deck `parent` edge — not from `deckId` appearing in this particular
+The task's delta is stamped `workspace:<workspaceId>`, derived server-side from the
+task → workspace `parent` edge — not from `workspaceId` appearing in this particular
 write, and not from whatever the agent happened to subscribe to. The routing is
-decided by the data: a slide belongs to its deck, so its writes go to the deck's
-group, full stop.
+decided by the data: a task belongs to its workspace, so its writes go to the
+workspace's group, full stop.
 
 ## See also
 
 - [Identity & Sync Groups](../identity.md) — the full scope / parent / grants model.
-- [Agent + Human](./agent-human.md) — yielding when a human edits the same row.
+- [Agent + Human](./agent-human.md) — yielding when someone else edits the same row.