@abloatai/ablo 0.5.1 → 0.7.0

package/docs/examples/agent-human.md

@@ -1,57 +1,57 @@
 # Agent + Human
 
-A task-writing agent that yields when a human is editing the same task.
+A report-writing agent that yields when a human is editing the same report.
 
 ## Scenario
 
-A product queue has tasks that humans and agents both update. They must not
+A product queue has reports that humans and agents both update. They must not
 collide:
 
 - If the user is editing, the agent waits or yields.
 - If the agent is updating, the UI can show who is active.
-- If the task changes mid-run, the commit rejects instead of overwriting newer
+- If the report changes mid-run, the commit rejects instead of overwriting newer
   state.
 
 ## Schema-Backed Worker
 
-Use the same schema client the app uses. The worker loads the task, checks active
-intents, and writes through `ablo.tasks.update(...)`.
+Use the same schema client the app uses. The worker loads the report, claims the
+row, and writes through `ablo.weatherReports.update(...)`.
 
 ```ts
 import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
-  tasks: model({
-    title: z.string(),
-    status: z.enum(['todo', 'doing', 'done']),
+  weatherReports: model({
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
   }),
 });
 
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
-export async function markDone(taskId: string) {
+export async function markReady(reportId: string) {
   await ablo.ready();
 
-  const [task] = await ablo.tasks.load({ where: { id: taskId } });
-  if (!task) return { status: 'not_found' };
-
-  const busy = ablo.intents.list({ resource: 'tasks', id: taskId });
-  if (busy.length > 0) return { status: 'busy', intents: busy };
-
-  const snap = ablo.snapshot({ tasks: taskId });
-  const updated = await ablo.tasks.update(
-    taskId,
-    { status: 'done' },
-    { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+  const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+  if (!report) return { status: 'not_found' };
+
+  const updated = await ablo.weatherReports.claim(
+    reportId,
+    async (claimed) =>
+      ablo.weatherReports.update(
+        claimed.id,
+        { status: 'ready' },
+        { wait: 'confirmed' },
+      ),
+    { wait: false, action: 'marking_ready' },
   );
 
-  return { status: 'done', task: updated };
+  return { status: 'ready', report: updated };
 }
 ```
 
-Advanced schema-less workers can use `Ablo({ apiKey }).agent(...)`, but that is
-not the first integration path.
+Keep workers on the same schema-backed client as the app.
 
 ## UI
 
@@ -60,16 +60,14 @@ not the first integration path.
 
 import { useAblo } from '@abloatai/ablo/react';
 
-export function TaskRow({ task: serverTask }: Props) {
-  const data = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;
-  const intents = useAblo((ablo) =>
-    ablo.intents.list({ resource: 'tasks', id: serverTask.id }),
-  ) ?? [];
-  const agentActive = intents.some((i) => i.participantKind === 'agent');
+export function ReportRow({ report: serverReport }: Props) {
+  const data = useAblo((ablo) => ablo.weatherReports.retrieve(serverReport.id)) ?? serverReport;
+  const active = useAblo((ablo) => ablo.weatherReports.claimState(serverReport.id));
+  const agentActive = active?.participantKind === 'agent';
 
   return (
     <div>
-      <span>{data.title}</span>
+      <span>{data.location}</span>
       {agentActive ? <span>Agent is updating...</span> : null}
     </div>
   );
@@ -78,7 +76,7 @@ export function TaskRow({ task: serverTask }: Props) {
 
 ## Why It Works
 
-- Intents are visible on read and over the live stream.
-- `ifBusy: 'wait'` lets agents wait for active work instead of racing.
+- Claims are visible through `claimState(id)` and over the live stream.
+- `claim(id, work)` lets agents wait for active work instead of racing.
 - `readAt` plus `onStale: 'reject'` turns mid-flight changes into typed errors.
 - Audit rows tie each accepted write back to the run that caused it.

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

@@ -9,10 +9,10 @@ import { streamText, tool } from 'ai';
 import { z } from 'zod';
 
 const schema = defineSchema({
-  tasks: model({
-    title: schemaZ.string(),
-    status: schemaZ.enum(['todo', 'doing', 'done']),
-    summary: schemaZ.string().optional(),
+  weatherReports: model({
+    location: schemaZ.string(),
+    status: schemaZ.enum(['pending', 'ready']),
+    forecast: schemaZ.string().optional(),
   }),
 });
 
@@ -21,35 +21,35 @@ const ablo = Ablo({
   apiKey: process.env.ABLO_API_KEY,
 });
 
-const updateTask = tool({
-  description: 'Update a task in the product database.',
+const updateReport = tool({
+  description: 'Update a weather report in the product database.',
   inputSchema: z.object({
-    taskId: z.string(),
-    status: z.enum(['todo', 'doing', 'done']).optional(),
-    summary: z.string().optional(),
+    reportId: z.string(),
+    status: z.enum(['pending', 'ready']).optional(),
+    forecast: z.string().optional(),
   }),
-  execute: async ({ taskId, status, summary }) => {
+  execute: async ({ reportId, status, forecast }) => {
     await ablo.ready();
 
-    const [task] = await ablo.tasks.load({ where: { id: taskId } });
-    if (!task) return { ok: false, reason: 'not_found' };
+    const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+    if (!report) return { ok: false, reason: 'not_found' };
 
-    const claim = ablo.tasks.intent(taskId);
-    if (claim.current) await claim.whenFree({ timeout: 30_000 });
+    // claim is advisory: if another participant holds the row, it waits for
+    // them to finish and re-reads before entering the callback. Released when
+    // the callback returns or throws.
+    return ablo.weatherReports.claim(
+      reportId,
+      async (claimed) => {
+        // update is stale-guarded under the held claim
+        const updated = await ablo.weatherReports.update(claimed.id, {
+          status: status ?? claimed.status,
+          forecast: forecast ?? claimed.forecast,
+        });
 
-    await claim.claim({ action: 'editing', field: 'status', ttl: '2m' });
-    try {
-      // update commits with the held claim and auto-releases on success
-      const updated = await claim.update({
-        status: status ?? task.status,
-        summary: summary ?? task.summary,
-      });
-
-      return { ok: true, task: updated };
-    } catch (err) {
-      await claim.finish();
-      throw err;
-    }
+        return { ok: true, report: updated };
+      },
+      { action: 'editing', ttl: '2m' },
+    );
   },
 });
 
@@ -59,7 +59,7 @@ export async function POST(req: Request) {
   return streamText({
     model,
     messages,
-    tools: { updateTask },
+    tools: { updateReport },
   }).toUIMessageStreamResponse();
 }
 ```
@@ -67,9 +67,8 @@ export async function POST(req: Request) {
 The important part is not the model provider. The important part is that the
 tool:
 
-- loads the latest task,
-- waits if another participant already holds the row,
-- acquires a claim before writing,
-- writes and auto-releases through the same handle,
+- loads the latest weather report,
+- claims the row (advisory — serializes behind any current holder, then re-reads),
+- writes through the normal stale-guarded `update`,
+- releases the claim automatically when the callback returns or throws,
 - waits for server confirmation.
-

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

@@ -9,7 +9,7 @@ that need multiplayer now and agent-safe writes later.
 
 This also applies to any API-backed app, not only Python. A product like a YC
 company's existing dashboard can keep its current endpoint/service/database
-shape and migrate one coordinated resource at a time.
+shape and migrate one coordinated model at a time.
 
 ```txt
 Browser UI
@@ -26,14 +26,14 @@ Browser UI
 Create a schema for the records that need realtime coordination.
 
 ```ts
-// web/ablo.schema.ts
+// web/ablo/schema.ts
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema({
-  tasks: model({
+  weatherReports: model({
     id: z.string(),
-    title: z.string(),
-    status: z.enum(['todo', 'doing', 'done']),
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
     updatedAt: z.string(),
   }),
 });
@@ -42,7 +42,7 @@ export const schema = defineSchema({
 ```ts
 // web/ablo.ts
 import Ablo from '@abloatai/ablo';
-import { schema } from './ablo.schema';
+import { schema } from './ablo/schema';
 
 export const ablo = Ablo({
   schema,
@@ -51,14 +51,14 @@ export const ablo = Ablo({
 ```
 
 Mount the React provider near the app root so client components can subscribe to
-model resources without importing server credentials.
+model clients without importing server credentials.
 
 ```tsx
 // web/app/providers.tsx
 'use client';
 
 import { AbloProvider } from '@abloatai/ablo/react';
-import { schema } from '@/ablo.schema';
+import { schema } from '@/ablo/schema';
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return <AbloProvider schema={schema}>{children}</AbloProvider>;
@@ -68,30 +68,32 @@ export function Providers({ children }: { children: React.ReactNode }) {
 ## 2. Add Live Reads In The UI
 
 Keep the first render backed by the existing Python endpoint. After that,
-subscribe to the same model resource Ablo writes through.
+subscribe to the same model client Ablo writes through.
 
 ```tsx
 'use client';
 
 import { useAblo } from '@abloatai/ablo/react';
 
-export function TaskRow({ task: serverTask }: { task: Task }) {
-  const task = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;
-  const intents = useAblo((ablo) =>
-    ablo.intents.list({ resource: 'tasks', id: serverTask.id }),
-  ) ?? [];
-  const busy = intents.length > 0;
+export function ReportRow({
+  report: serverReport,
+}: {
+  report: { id: string; location: string; status: string };
+}) {
+  const report = useAblo((ablo) => ablo.weatherReports.retrieve(serverReport.id)) ?? serverReport;
+  const active = useAblo((ablo) => ablo.weatherReports.claimState(serverReport.id));
+  const claimed = Boolean(active);
 
   return (
-    <button disabled={busy || task.status === 'done'}>
-      {busy ? 'Someone is editing' : task.title}
+    <button disabled={claimed || report.status === 'ready'}>
+      {claimed ? 'Someone is editing' : report.location}
     </button>
   );
 }
 ```
 
 No string model key is needed in the first example. The selector reads from
-`ablo.tasks`, so React uses the same model resource as writes and agents.
+`ablo.weatherReports`, so React uses the same model client as writes and agents.
 
 ## 3. Add One Python Data Source Endpoint
 
@@ -120,7 +122,7 @@ import os
 import time
 from fastapi import APIRouter, HTTPException, Request
 
-from app.services.tasks import get_task, list_tasks, apply_task_operations
+from app.services.reports import get_report, list_reports, apply_report_operations
 
 router = APIRouter()
 
@@ -160,15 +162,15 @@ async def ablo_source(request: Request):
     body = json.loads(raw_body)
 
     if body["type"] == "load":
-        if body["model"] == "tasks":
-            return {"row": await get_task(body["id"])}
+        if body["model"] == "weatherReports":
+            return {"row": await get_report(body["id"])}
 
     if body["type"] == "list":
-        if body["model"] == "tasks":
-            return {"rows": await list_tasks(body.get("query", {}))}
+        if body["model"] == "weatherReports":
+            return {"rows": await list_reports(body.get("query", {}))}
 
     if body["type"] == "commit":
-        rows = await apply_task_operations(
+        rows = await apply_report_operations(
             operations=body["operations"],
             client_tx_id=body.get("clientTxId"),
             scope=body.get("scope", {}),
@@ -178,7 +180,7 @@ async def ablo_source(request: Request):
     raise HTTPException(status_code=400, detail="unsupported request")
 ```
 
-`apply_task_operations` should reuse the same transaction and validation logic
+`apply_report_operations` should reuse the same transaction and validation logic
 the existing Python endpoints already use. Dedupe by `clientTxId` so retries are
 safe.
 
@@ -193,20 +195,20 @@ Button -> Python endpoint -> service -> database
 Target button path:
 
 ```txt
-Button -> ablo.tasks.update(...)
+Button -> ablo.weatherReports.update(...)
 Ablo -> Python Data Source endpoint
 Python service -> database
 Ablo -> realtime fanout and receipt
 ```
 
-The app does not need a flag-day rewrite. Move one resource at a time.
+The app does not need a flag-day rewrite. Move one model at a time.
 
 ```ts
-const snap = ablo.snapshot({ tasks: taskId });
+const snap = ablo.snapshot({ weatherReports: reportId });
 
-await ablo.tasks.update(
-  taskId,
-  { status: 'done' },
+await ablo.weatherReports.update(
+  reportId,
+  { status: 'ready' },
   { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
 );
 ```
@@ -235,12 +237,12 @@ and timestamp. If the change originated from an Ablo commit, include the same
 Agents use the same model API as the UI:
 
 ```ts
-const [task] = await ablo.tasks.load({ where: { id: taskId } });
-const snap = ablo.snapshot({ tasks: taskId });
+const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+const snap = ablo.snapshot({ weatherReports: reportId });
 
-await ablo.tasks.update(
-  taskId,
-  { status: 'done' },
+await ablo.weatherReports.update(
+  reportId,
+  { status: 'ready' },
   { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
 );
 ```

package/docs/examples/nextjs.md

@@ -7,11 +7,11 @@ Server Components, and live client subscriptions.
 
 ```txt
 app/
-  tasks/
+  reports/
     [id]/
       page.tsx          # RSC: retrieve + render
       actions.ts        # Server Action: schema update with stale-state check
-      TaskEditor.tsx    # Client: live updates
+      ReportEditor.tsx    # Client: live updates
   lib/
     ablo.ts             # Schema-backed Ablo client for server actions
 ```
@@ -19,40 +19,41 @@ app/
 ## RSC Initial Render
 
 ```tsx
-// app/tasks/[id]/page.tsx
+// app/reports/[id]/page.tsx
 import { ablo } from '@/lib/ablo';
 
-export default async function TaskPage({
+export default async function ReportPage({
   params,
 }: { params: { id: string } }) {
   await ablo.ready();
-  const [task] = await ablo.tasks.load({ where: { id: params.id } });
-  if (!task) return null;
+  const [report] = await ablo.weatherReports.load({ where: { id: params.id } });
+  if (!report) return null;
 
-  return <TaskEditor task={task} />;
+  return <ReportEditor report={report} />;
 }
 ```
 
 ## Server Action Commit
 
 ```ts
-// app/tasks/[id]/actions.ts
+// app/reports/[id]/actions.ts
 'use server';
 
 import { ablo } from '@/lib/ablo';
 
-export async function markDone(id: string) {
-  const busy = ablo.intents.list({ resource: 'tasks', id });
-  if (busy.length > 0) return { status: 'busy', intents: busy };
-
-  const snap = ablo.snapshot({ tasks: id });
-  const task = await ablo.tasks.update(
+export async function markReady(id: string) {
+  const report = await ablo.weatherReports.claim(
     id,
-    { status: 'done' },
-    { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+    async (claimed) =>
+      ablo.weatherReports.update(
+        claimed.id,
+        { status: 'ready' },
+        { wait: 'confirmed' },
+      ),
+    { wait: false, action: 'marking_ready' },
   );
 
-  return { status: 'done', task };
+  return { status: 'ready', report };
 }
 ```
 
@@ -66,16 +67,14 @@ rejects. The action can re-fetch and ask the user to retry.
 
 import { useAblo } from '@abloatai/ablo/react';
 
-export function TaskEditor({ task: serverTask }: Props) {
-  const data = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;
-  const intents = useAblo((ablo) =>
-    ablo.intents.list({ resource: 'tasks', id: serverTask.id }),
-  ) ?? [];
-  const busy = intents.length > 0;
+export function ReportEditor({ report: serverReport }: Props) {
+  const data = useAblo((ablo) => ablo.weatherReports.retrieve(serverReport.id)) ?? serverReport;
+  const active = useAblo((ablo) => ablo.weatherReports.claimState(serverReport.id));
+  const claimed = Boolean(active);
 
   return (
-    <button disabled={busy || data.status === 'done'}>
-      {busy ? 'Someone is editing' : 'Mark done'}
+    <button disabled={claimed || data.status === 'ready'}>
+      {claimed ? 'Someone is editing' : 'Mark ready'}
     </button>
   );
 }

package/docs/examples/scoped-agent.md

@@ -0,0 +1,78 @@
+# Agent Scoped to One Deck
+
+An agent that edits **one deck** and receives realtime updates for **only that
+deck** — not the whole org. Shows the sync-group model end to end: a scope root,
+a containment (`parent`) edge, identity roles, and the model-form `scope`.
+
+See [Identity & Sync Groups](../identity.md) for the full reference.
+
+## 1. Schema — declare the scope, once
+
+```ts
+import { defineSchema, identityRole, model, relation, z } from '@abloatai/ablo/schema';
+
+export const schema = defineSchema(
+  {
+    // A scope root: deck rows form the group `deck:<id>`.
+    decks: model(
+      { title: z.string() },
+      {},
+      { orgScoped: true, scope: 'deck' },
+    ),
+    // A child: no group of its own. It inherits its deck's group via the
+    // `parent` edge, so a slide write reaches everyone viewing the deck —
+    // even a slide edit that doesn't touch `deckId` (routing is keyed on the
+    // row's id, not the changed columns).
+    slides: model(
+      { deckId: z.string(), body: z.string() },
+      { deck: relation.belongsTo('decks', 'deckId', { parent: true }) },
+      { orgScoped: true },
+    ),
+  },
+  {
+    // Humans get their full org scope automatically from these.
+    identityRoles: [
+      identityRole({ kind: 'org', source: 'organizationId' }),
+      identityRole({ kind: 'user', source: 'userId' }),
+    ],
+  },
+);
+```
+
+## 2. Dispatch — narrow the agent to the deck it's working on
+
+The agent inherits the triggering user's identity (its ceiling) and is narrowed
+to one deck (the floor). You pass the **model and id** — never a `deck:<id>`
+string; the engine builds the group from the model's `scope`.
+
+```ts
+const ablo = Ablo({
+  schema,
+  url: process.env.ABLO_URL,
+  kind: 'agent',
+  agentId: 'agent:slide-writer',
+  userId: triggeringUser.id,     // ceiling: can't exceed this user's reach
+  organizationId: triggeringUser.organizationId,
+  scope: { decks: deckId },      // floor: just this deck → deck:<deckId>
+});
+await ablo.ready();
+```
+
+## 3. Write — it fans out to everyone on that deck
+
+```ts
+// 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(slideId, { body: 'Q4 revenue up 12% YoY' });
+```
+
+The slide's delta is stamped `deck:<deckId>` (derived server-side from the
+slide → deck `parent` edge), so it reaches the deck's audience authoritatively —
+regardless of which groups the agent happened to subscribe to. And `scope` only
+ever *narrows*: the agent can't reach a deck its triggering user couldn't.
+
+## 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.

package/docs/examples/server-agent.md

@@ -8,10 +8,10 @@ import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
-  tasks: model({
-    title: z.string(),
-    status: z.enum(['todo', 'doing', 'done']),
-    summary: z.string().optional(),
+  weatherReports: model({
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
+    forecast: z.string().optional(),
   }),
 });
 
@@ -20,67 +20,26 @@ const ablo = Ablo({
   apiKey: process.env.ABLO_API_KEY,
 });
 
-export async function completeTask(taskId: string) {
+export async function completeReport(reportId: string) {
   await ablo.ready();
 
-  const [task] = await ablo.tasks.load({ where: { id: taskId } });
-  if (!task) return { status: 'not_found' };
-
-  const busy = ablo.intents.list({ resource: 'tasks', id: taskId });
-  if (busy.length > 0) {
-    return { status: 'busy', intents: busy };
-  }
-
-  const snap = ablo.snapshot({ tasks: taskId });
-  const updated = await ablo.tasks.update(
-    taskId,
-    { status: 'done' },
-    { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+  const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+  if (!report) return { status: 'not_found' };
+
+  const updated = await ablo.weatherReports.claim(
+    reportId,
+    async (claimed) =>
+      ablo.weatherReports.update(
+        claimed.id,
+        { status: 'ready' },
+        { wait: 'confirmed' },
+      ),
+    { wait: false, action: 'completing' },
   );
 
-  return { status: 'done', task: updated };
+  return { status: 'ready', report: updated };
 }
 ```
 
-## Advanced Schema-Less Run
-
-Use `agent.run(...)` when the worker intentionally cannot import the app schema.
-It creates the run envelope and returns `done`, `failed`, or `cancelled`.
-
-```ts
-const api = Ablo({ apiKey: process.env.ABLO_API_KEY });
-
-const result = await api.agent('task-writer', {
-  can: ['tasks.retrieve', 'tasks.update'],
-  syncGroups: ['workspace:acme'],
-}).run(
-  {
-    prompt: 'Mark task_123 done.',
-    surface: 'agent_worker',
-  },
-  async ({ resource }) => {
-    const tasks = resource<{ title: string; status: string }>('tasks');
-
-    const { data, stamp, intents } = await tasks.retrieve('task_123', {
-      ifBusy: 'return',
-    });
-
-    if (intents.length > 0) {
-      return { skipped: true, reason: 'busy' };
-    }
-
-    return tasks.update(
-      'task_123',
-      { status: 'done' },
-      { readAt: stamp, onStale: 'reject', wait: 'confirmed' },
-    );
-  },
-);
-
-if (result.status === 'failed') throw result.error;
-if (result.status === 'cancelled') return;
-```
-
-Use the schema-backed version first. The schema-less version is for generic
-agent infrastructure, MCP routes, and platform code.
-
+Use the schema-backed version for server agents so the worker, app, and React UI
+share the same model methods.