@abloatai/ablo 0.16.2 → 0.17.0

package/dist/client/Ablo.js

@@ -518,17 +518,30 @@ function createDynamicModelClass(modelName, jsonSubFields, fieldNames, computed,
     }
     return ModelClass;
 }
-// ── Default console logger ────────────────────────────────────────────────
-const consoleLogger = {
-    debug: (...args) => { if (typeof console !== 'undefined')
-        console.debug('[sync]', ...args); },
-    info: (...args) => { if (typeof console !== 'undefined')
-        console.info('[sync]', ...args); },
-    warn: (...args) => { if (typeof console !== 'undefined')
-        console.warn('[sync]', ...args); },
-    error: (...args) => { if (typeof console !== 'undefined')
-        console.error('[sync]', ...args); },
-};
+const LOG_LEVEL_RANK = { debug: 10, info: 20, warn: 30, error: 40, silent: 99 };
+function resolveLogLevel() {
+    // `globalThis.process` guard keeps this safe in browser/edge runtimes that
+    // have no `process` binding — there we fall through to the default.
+    const raw = globalThis.process?.env?.ABLO_LOG_LEVEL;
+    const normalized = raw?.toLowerCase();
+    if (normalized && normalized in LOG_LEVEL_RANK)
+        return normalized;
+    return 'warn';
+}
+const consoleLogger = (() => {
+    const threshold = LOG_LEVEL_RANK[resolveLogLevel()];
+    const emit = (level, fn, args) => {
+        if (typeof console === 'undefined' || LOG_LEVEL_RANK[level] < threshold)
+            return;
+        fn('[sync]', ...args);
+    };
+    return {
+        debug: (...args) => emit('debug', console.debug, args),
+        info: (...args) => emit('info', console.info, args),
+        warn: (...args) => emit('warn', console.warn, args),
+        error: (...args) => emit('error', console.error, args),
+    };
+})();
 // `readProcessEnv` lives in `./auth` alongside the other resolvers
 // that read it. Re-exported there for use elsewhere in the file.
 // ── Default mutation executor (wire: `commit` frame over WebSocket) ──────

package/dist/schema/diff.d.ts

@@ -133,6 +133,20 @@ export interface MigrationSignal {
     readonly model: string;
     readonly field?: string;
     readonly detail: string;
+    /**
+     * Reader-visibility context for a removal that shadows an existing artifact:
+     * the active schema this push is being diffed against. Lets the CLI show the
+     * baseline — version + WHEN it was pushed — so "incompatible" isn't a mystery
+     * (e.g. a first sandbox push diffed against a months-old production schema).
+     */
+    readonly shadowed?: {
+        readonly environment: string;
+        readonly version: number;
+        /** ISO timestamp the shadowed artifact was activated/pushed, or null. */
+        readonly pushedAt: string | null;
+        /** Who pushed it (e.g. `apikey:…`), or null. */
+        readonly pushedBy: string | null;
+    };
 }
 export interface MigrationClassification {
     /** Execute but may lose or risk data on a non-empty table. */

package/docs/agent-messaging.md

@@ -0,0 +1,149 @@
+# Agent Messaging
+
+Use a normal model when agents or humans need durable communication inside a
+syncGroup. Use claim `description` and `meta` for live coordination context.
+Use a `messages` row when the information must survive reconnects, work over
+HTTP, or be replayed from the sync cursor.
+
+## The rule
+
+| Need | Use | Why |
+| --- | --- | --- |
+| "I am holding this row because..." | `claim({ reason, description, meta })` | Live and low-latency. Peers see it through presence while the claim exists. |
+| "Remember this handoff/status/request" | A `messages` model | Durable row. Ordered in `sync_deltas`, replayed after reconnect, readable by HTTP agents. |
+
+Claim context is ephemeral. If a participant was offline, reconnected later, or
+only uses `transport: "http"`, it can miss claim/presence frames. Message rows
+are facts in your database and in the sync log.
+
+## Schema
+
+Add a `messages` model to the same schema as the work it discusses. Scope it
+with the same field that scopes the work row.
+
+```ts
+import Ablo from "@abloatai/ablo";
+import { defineSchema, entityRole, model, z } from "@abloatai/ablo/schema";
+
+export const schema = defineSchema({
+  workItems: model(
+    {
+      title: z.string(),
+      status: z.string(),
+      teamId: z.string(),
+    },
+    {},
+    { entityRoles: [entityRole({ kind: "team", source: "teamId" })] },
+  ),
+
+  messages: model(
+    {
+      body: z.string(),
+      kind: z.enum(["status", "request", "handoff"]),
+      teamId: z.string(),
+
+      // Causal link back to coordination or the row being discussed.
+      aboutEntityType: z.string().optional(),
+      aboutEntityId: z.string().optional(),
+      aboutIntentId: z.string().optional(),
+    },
+    {},
+    { entityRoles: [entityRole({ kind: "team", source: "teamId" })] },
+  ),
+});
+```
+
+Push the schema before agents call it:
+
+```bash
+npx ablo push
+```
+
+## Server-side agent
+
+Most server-side agents use the direct database path. Pass the schema, API key,
+database URL, and transport selector:
+
+```ts
+const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+  databaseUrl: process.env.DATABASE_URL,
+  transport: "http",
+});
+
+await ablo.ready();
+```
+
+`databaseUrl` is server-only. Browser clients must not receive it; live UIs use
+the default WebSocket transport with a minted user/session token.
+
+If your backend mints restricted agent tokens, register the database once from a
+secret-key server process as above. Workers using the restricted token can then
+construct `Ablo({ schema, authToken, transport: "http" })` because the project
+already has a registered data plane.
+
+## Link a message to a claim
+
+The claim id is the causal id. Store it in `aboutIntentId` when the message is
+about work currently protected by a claim.
+
+```ts
+const claim = await ablo.workItems.claim({
+  id: workItemId,
+  reason: "reformatting",
+  description: "normalizing the pricing table",
+  meta: { estimateSeconds: 120 },
+  queue: false,
+});
+
+try {
+  await ablo.messages.create({
+    id: crypto.randomUUID(),
+    data: {
+      body: "Taking the pricing table for about two minutes.",
+      kind: "status",
+      teamId,
+      aboutEntityType: "workItems",
+      aboutEntityId: workItemId,
+      aboutIntentId: claim.claimId,
+    },
+    wait: "confirmed",
+  });
+} finally {
+  await claim.release();
+}
+```
+
+Peers in `team:${teamId}` receive the message through the normal delta stream.
+Peers outside that syncGroup do not.
+
+## Reading messages
+
+Live clients read locally and update when deltas arrive:
+
+```ts
+const rows = ablo.messages.getAll({
+  where: { teamId },
+  orderBy: { createdAt: "asc" },
+});
+```
+
+HTTP agents read by request:
+
+```ts
+const rows = await ablo.messages.list({
+  where: { teamId },
+  orderBy: { createdAt: "asc" },
+});
+```
+
+Because messages are ordinary synced rows, reconnecting clients catch up from
+their cursor and see the rows they missed while offline.
+
+## Retention
+
+Deleting or archiving old `messages` rows is your app's policy. The sync log is
+still durable audit/history: `sync_deltas` has no message-specific TTL. That is
+useful for coordination and compliance, but a chat-scale product should plan
+retention before writing high-volume conversation traffic.

package/docs/agents.md

@@ -0,0 +1,104 @@
+# Agents
+
+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 (the Stripe server-SDK / Liveblocks-node shape).
+
+Humans get the live plane (WebSocket: presence, optimistic, sub-100ms). Agents
+get the stateless plane (HTTP). **Both operate on the same typed, coordinated
+state — and coordinate *with each other*.**
+
+<Note>
+Agents transact against your **pushed schema**, same as everyone — `ablo.tasks`
+exists because you defined a `task` model and ran `ablo push`. The key
+authenticates; the [schema](/quickstart) defines what you can call.
+</Note>
+
+## The agent client
+
+Same `Ablo()` entry point as everywhere else — pass `transport: 'http'`. No
+socket, no connection state — just your schema (for types) and an API key.
+
+```ts
+import Ablo from "@abloatai/ablo";
+import { schema } from "./schema";
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: "http" });
+
+// Reads + writes, fully typed off your schema — each is one HTTP round-trip:
+const open = await ablo.tasks.list({ where: { status: "todo" } });
+const { data } = await ablo.tasks.retrieve({ id: open[0].id });
+await ablo.tasks.update({ id: open[0].id, data: { status: "done" } });
+```
+
+It exposes `retrieve` / `list` / `create` / `update` / `delete`, plus `commits`
+and `claim`. It does **not** expose the stateful-only surface (`get` /
+`getAll` / `getCount` local reads, `onChange` live subscription) — those need a
+live connection, so with `transport: 'http'` the return type narrows and they
+are a *compile error*, not a runtime surprise.
+
+## Coordination — claim, queue, reorder
+
+The differentiator. A claim is a **durable lease + FIFO wait-line** on a row —
+"who's working on this, who's waiting" — and it's request/response, so an agent
+holds it over HTTP. This is how two agents (or an agent and a human) don't
+clobber the same record.
+
+```ts
+// Acquire a lease, do work with the held row, release on scope exit:
+await using claim = await ablo.tasks.claim({ id: taskId });
+const task = claim.data;
+// …no one else can hold this row while you work…
+await ablo.tasks.update({ id: task.id, data: { status: "in_review" } });
+
+await ablo.tasks.claim.state({ id: taskId });   // who holds it now (or null)
+await ablo.tasks.claim.queue({ id: taskId });   // the FIFO wait-line behind the holder
+await ablo.tasks.claim.reorder({ id: taskId, order: line }); // re-rank the line (privileged)
+```
+
+Think of it as a queue per row — a durable, inspectable, reorderable lease line
+("SQS for entity contention"). Use `{ queue: false }` for fail-fast dedup: *if
+someone else has this job, skip it.*
+
+## Messaging between agents
+
+Use claim `description` and `meta` for live "what I am doing now" context. Use
+ordinary synced rows for handoffs, status notes, and requests that must survive
+reconnects or be readable by HTTP agents. The recipe is a `messages` model
+scoped by the same syncGroup field as the work row, with `aboutIntentId` linking
+a message back to the claim it discusses.
+
+See [Agent Messaging](/agent-messaging) for the schema and direct
+`databaseUrl` setup.
+
+## Humans + agents on one state
+
+There's no separate "agent mode." A human editing a record over their WebSocket
+and an agent acting over HTTP share the same typed state and the same coordination
+plane: the agent can claim the row a human is editing (and wait in line), and the
+human sees the agent's committed changes stream in **live** — over the human's
+own socket, even though the agent committed over HTTP. You write the agent once;
+it's a first-class participant, not a bolt-on.
+
+## How an agent runs
+
+```text
+something happens ──▶ your agent (HTTP, no socket)
+  (a job, a webhook,     read context (list/retrieve)
+   a queue message)      claim → work → commit
+                         done — no held connection
+```
+
+Because it holds nothing open, an agent is a **stateless worker**: deploys and
+restarts are free, and you scale by adding workers. A long-running fleet of idle
+agents costs nothing on the live plane — that capacity stays for humans.
+
+## What stays on the live (human) plane
+
+`onChange` (live subscriptions) and `get`/`getAll`/`getCount` (local synced-pool
+reads) require a WebSocket and a local store — they're for interactive UIs, not
+stateless agents. An agent reacts to an external trigger (a job/queue/webhook),
+then reads with `list`/`retrieve`. See [client behavior](/client-behavior) for
+the full surface and [guarantees](/guarantees) for the coordination semantics.