@abloatai/ablo 0.59.2 → 0.60.0

package/examples/terminal-showcase/index.ts

@@ -0,0 +1,219 @@
+/**
+ * A deterministic terminal proof of Ablo's product contract.
+ *
+ * It uses a real Ablo project, mints distinct human and agent participants,
+ * proves stale work is rejected, then proves claim contention serializes the
+ * same two participants onto fresh state. The final write is looked up through
+ * the durable commit API so the terminal shows evidence, not just application
+ * output.
+ *
+ * Run from packages/ablo:
+ *
+ *   npx ablo push --schema examples/terminal-showcase/schema.ts
+ *   ABLO_API_KEY=sk_... npx tsx examples/terminal-showcase/index.ts
+ */
+import Ablo, { AbloStaleContextError } from '@abloatai/ablo';
+import Sessions from '@abloatai/ablo/sessions';
+import { schema } from './schema';
+
+const apiKey = process.env.ABLO_API_KEY;
+if (!apiKey?.startsWith('sk_')) {
+  throw new Error('ABLO_API_KEY must be a secret sk_ project key so the demo can mint scoped participants.');
+}
+
+const delayMs = Number.parseInt(process.env.ABLO_SHOWCASE_DELAY_MS ?? '650', 10);
+const keepRow = process.env.ABLO_SHOWCASE_KEEP === '1';
+const color = process.stdout.isTTY && process.env.NO_COLOR === undefined;
+const ink = {
+  blue: (value: string) => color ? `\u001B[34m${value}\u001B[39m` : value,
+  dim: (value: string) => color ? `\u001B[2m${value}\u001B[22m` : value,
+  green: (value: string) => color ? `\u001B[32m${value}\u001B[39m` : value,
+  red: (value: string) => color ? `\u001B[31m${value}\u001B[39m` : value,
+  yellow: (value: string) => color ? `\u001B[33m${value}\u001B[39m` : value,
+};
+
+function pause(ms = delayMs): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function heading(index: number, title: string): void {
+  console.log(`\n${ink.blue(String(index).padStart(2, '0'))}  ${title}`);
+}
+
+function fact(label: string, value: unknown): void {
+  console.log(`    ${ink.dim(label.padEnd(16))}${String(value)}`);
+}
+
+function ok(message: string): void {
+  console.log(`    ${ink.green('✓')} ${message}`);
+}
+
+async function main(): Promise<void> {
+  const control = Ablo({ schema, apiKey });
+  const sessions = Sessions({ schema, apiKey });
+  const participants: Array<{ dispose(): Promise<void> }> = [];
+  let dealId: string | undefined;
+  let humanClaim: { release(): Promise<void> } | undefined;
+  let agentClaim: { release(): Promise<void> } | undefined;
+
+  console.log();
+  console.log('  ABLO / ONE ROW, TWO ACTORS, ONE CONFIRMED REALITY');
+  console.log(ink.dim('  Real credentials · real coordination · no model call · no simulated server'));
+
+  try {
+    await control.ready();
+
+    heading(1, 'Create one shared row');
+    const deal = await control.deals.create({
+      data: {
+        name: `Northstar renewal ${Date.now().toString(36)}`,
+        stage: 'open',
+        value: 100_000,
+        revision: 1,
+        note: 'Initial account plan',
+      },
+    });
+    dealId = deal.id;
+    fact('row', `${deal.id} · revision ${deal.revision}`);
+    ok('create resolved after authoritative confirmation');
+
+    heading(2, 'Give each actor its own bounded authority');
+    const humanSession = await sessions.create({
+      user: { id: `showcase-human-${deal.id}` },
+      can: { deals: ['read', 'update'] },
+      ttlSeconds: 300,
+    });
+    const agentSession = await sessions.create({
+      agent: { id: `showcase-agent-${deal.id}` },
+      onBehalfOf: { user: { id: `showcase-human-${deal.id}` } },
+      can: { deals: ['read', 'update'] },
+      ttlSeconds: 300,
+    });
+    const human = Ablo({ schema, session: humanSession, transport: 'http' });
+    const pricingAgent = Ablo({ schema, session: agentSession, transport: 'http' });
+    participants.push(human, pricingAgent);
+    await Promise.all([human.ready(), pricingAgent.ready()]);
+    fact('human', `${human.identity?.participantKind}:${human.identity?.participantId}`);
+    fact('agent', `${pricingAgent.identity?.participantKind}:${pricingAgent.identity?.participantId}`);
+    fact('agent can', pricingAgent.identity?.operations.join(', '));
+
+    heading(3, 'Reject reasoning built on stale state');
+    const agentRead = await pricingAgent.deals.read({ id: deal.id });
+    if (!agentRead) throw new Error('The agent could not read the showcase row.');
+    fact('agent reads', `revision ${agentRead.revision} · value ${agentRead.value}`);
+    console.log(`    ${ink.yellow('…')} agent starts a slow pricing calculation`);
+    await pause();
+
+    const humanEdit = await human.deals.update({
+      id: deal.id,
+      data: {
+        value: 120_000,
+        revision: 2,
+        note: 'Human added the expansion seats',
+      },
+    });
+    fact('human writes', `revision ${humanEdit.revision} · value ${humanEdit.value}`);
+
+    try {
+      await pricingAgent.deals.update({
+        id: deal.id,
+        data: {
+          value: 105_000,
+          revision: 2,
+          note: 'Price calculated from revision 1',
+        },
+        reads: [agentRead],
+        idempotencyKey: `showcase:${deal.id}:stale-price`,
+      });
+      throw new Error('The stale write unexpectedly landed.');
+    } catch (error) {
+      if (!(error instanceof AbloStaleContextError)) throw error;
+      console.log(`    ${ink.red('REJECTED')} ${error.code} — the human edit was not overwritten`);
+    }
+
+    const afterRejection = await control.deals.get({ id: deal.id });
+    if (!afterRejection) throw new Error('The showcase row disappeared after stale rejection.');
+    fact('still true', `revision ${afterRejection.revision} · value ${afterRejection.value}`);
+
+    heading(4, 'Serialize slow work with a visible claim');
+    const claimedByHuman = await human.deals.claim({
+      id: deal.id,
+      description: 'reviewing commercial terms',
+      ttl: '30s',
+    });
+    humanClaim = claimedByHuman;
+    fact('human holds', `fence ${claimedByHuman.fenceToken}`);
+
+    const queuedClaim = pricingAgent.deals.claim({
+      id: deal.id,
+      description: 'recalculating final price',
+      ttl: '30s',
+      queue: true,
+    });
+    await pause();
+    const queue = await control.deals.claim.queue({ id: deal.id });
+    fact('agent waits', `${queue.size} participant in FIFO queue`);
+
+    await human.deals.update({
+      id: deal.id,
+      data: {
+        stage: 'reviewing',
+        revision: 3,
+        note: 'Commercial review complete',
+      },
+      claim: claimedByHuman,
+      idempotencyKey: `showcase:${deal.id}:human-review`,
+    });
+    await claimedByHuman.release();
+    humanClaim = undefined;
+
+    const claimedByAgent = await queuedClaim;
+    agentClaim = claimedByAgent;
+    fact('agent receives', `fresh revision ${claimedByAgent.data.revision} · fence ${claimedByAgent.fenceToken}`);
+    ok('the queued agent did not continue from its earlier revision 1 read');
+
+    heading(5, 'Commit and inspect the durable evidence');
+    const commitId = `showcase:${deal.id}:agent-approval`;
+    const confirmed = await pricingAgent.deals.update({
+      id: deal.id,
+      data: {
+        stage: 'approved',
+        value: 118_000,
+        revision: 4,
+        note: 'Repriced from the fresh claimed row',
+      },
+      claim: claimedByAgent,
+      idempotencyKey: commitId,
+    });
+    await claimedByAgent.release();
+    agentClaim = undefined;
+
+    const evidence = await control.commits.get({ id: commitId });
+    if (!evidence) throw new Error(`Durable commit ${commitId} was not found.`);
+    fact('row', `${confirmed.id} · revision ${confirmed.revision} · ${confirmed.stage}`);
+    fact('commit', commitId);
+    fact('status', evidence.status);
+    fact('actor', `${evidence.actor.kind}:${evidence.actor.id}`);
+    fact('claim refs', evidence.claims.length);
+    fact('attempts', evidence.attempts.length);
+    fact('confirmation', `${Date.parse(evidence.statusAt) - Date.parse(evidence.createdAt)} ms`);
+    ok('the authoritative source confirmed the write before the SDK resolved');
+
+    console.log();
+    console.log(`  ${ink.green('PROVEN')} stale work did not land · contenders serialized · fresh state won · evidence persisted`);
+    if (keepRow) fact('kept row', deal.id);
+  } finally {
+    await agentClaim?.release().catch(() => undefined);
+    await humanClaim?.release().catch(() => undefined);
+    await Promise.all(participants.map((participant) => participant.dispose()));
+    if (dealId && !keepRow) {
+      await control.deals.delete({ id: dealId }).catch(() => undefined);
+    }
+    await control.dispose();
+  }
+}
+
+main().catch((error: unknown) => {
+  console.error(`\n  ${ink.red('SHOWCASE FAILED')}`, error);
+  process.exitCode = 1;
+});

package/examples/terminal-showcase/schema.ts

@@ -0,0 +1,12 @@
+/** The isolated model used by the terminal product proof. */
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
+
+export const schema = defineSchema({
+  deals: model({
+    name: z.string(),
+    stage: z.enum(['open', 'reviewing', 'approved']),
+    value: z.number(),
+    revision: z.number(),
+    note: z.string(),
+  }),
+});

package/llms.txt

@@ -66,7 +66,7 @@ Responses also carry `RateLimit-Policy` (the standing allowance, e.g. `"secret";
 
 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.
+- SDK, `@abloatai/ablo` — API-key service clients use HTTP; scoped session clients use one reconnecting WebSocket by default. The credential is the identity in both cases.
 - 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/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).
@@ -153,8 +153,8 @@ beside the rows. Pass `nextCursor` back as `cursor`, keeping `where` and
 `orderBy` the same, to walk the rest. Check `hasMore` before treating a result
 as complete.
 
-Workers import the same app schema and select `transport: 'http'`. The transport
-changes; the typed `ablo.<model>` contract does not. There is no public
+Workers import the same app schema. API-key workers use HTTP; session workers
+use WebSocket by default. The typed `ablo.<model>` contract does not change. There is no public
 schema-less or string-keyed model client.
 
 React reads should use selector `useAblo`: `useAblo((ablo) => ablo.weatherReports.local.get(id))` (synchronous local read, reactive in render).
@@ -269,13 +269,13 @@ one direct mutation with a typed `ablo.<model>.update(...)`, use selector
 
 A PLANE is what a credential acts on: `production` is the root branch and development/preview branches are children. Rows, the registered database, and the active schema artifact are all PER PLANE. Every `sk_` has an immutable persisted branch binding; its spelling does not distinguish root from child, so app code never passes an environment. A child copies its parent's active schema at creation and owns its artifact after that. A CHILD push does NOT reach production. Production gets models only when the reviewed deployment pushes to the root.
 
-Going live is three things, each done with a root-bound `sk_` key: register the production database (`ablo connect apply` — the DIRECT host, never a pooler; a pooler refuses in the words of a wrong password), push the schema AHEAD of the code that needs it, and hold the right credential per runtime (server/serverless `sk_`; browser `pk_` read-only or an `authEndpoint` minting `ek_`). `ablo login` stores an `mk_` management credential and CANNOT read/write application data or push the production schema — a production push needs a root-bound `sk_` in `ABLO_API_KEY`. Gate a deploy on `npx ablo status --json` having an EMPTY `blockers` array; each blocker carries a `problem` and the one `fix`. Your agents do NOT each hold a database connection — they talk to Ablo, and Ablo holds at most 4 connections per plane (`application_name = 'ablo-direct-writer'`) however many callers write behind them, so size the database for that number and not for your agent count. Read `deployment` for the full path.
+Going live is three things, each done with a root-bound `sk_` key: register the production database (`ablo connect apply` — the DIRECT host, never a pooler; a pooler refuses in the words of a wrong password), push the schema AHEAD of the code that needs it, and hold the right credential per runtime (server/serverless `sk_`; browser `pk_` read-only or `session: { endpoint }` minting `ek_`). `ablo login` stores an `mk_` management credential and CANNOT read/write application data or push the production schema — a production push needs a root-bound `sk_` in `ABLO_API_KEY`. Gate a deploy on `npx ablo status --json` having an EMPTY `blockers` array; each blocker carries a `problem` and the one `fix`. Your agents do NOT each hold a database connection — they talk to Ablo, and Ablo holds at most 4 connections per plane (`application_name = 'ablo-direct-writer'`) however many callers write behind them, so size the database for that number and not for your agent count. Read `deployment` for the full path.
 
 ## Public Surface
 
 Import from these public paths only:
 
-- `@abloatai/ablo` — headless HTTP `Ablo`, errors, typed model clients, claims, durable observation, and `dataSource`.
+- `@abloatai/ablo` — headless `Ablo` (API-key HTTP or session WebSocket), 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.
@@ -288,10 +288,10 @@ Import from these public paths only:
 
 Do not teach `/api`, `/agent`, `/core`, `/realtime`, or internal subpaths. (`/source` and `/ai-sdk` are public.)
 
-`onChange` is WebSocket-only. It exists on the reactive client because that
-client holds an open socket and a local graph. The stateless HTTP client does
-not expose it at the type or runtime level; HTTP agents re-read or inspect
-durable logs instead.
+`context().onChange` uses a one-shot SSE response for an HTTP client and reuses
+the session socket for a session client. The
+human-facing client also owns a socket and local graph. A session identifies the
+caller; it is not itself a transport.
 
 ## CLI: agents run it NON-INTERACTIVELY
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.59.2",
+  "version": "0.60.0",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -65,6 +65,11 @@
       "import": "./dist/auth.js",
       "default": "./dist/auth.js"
     },
+    "./sessions": {
+      "types": "./dist/sessions.d.ts",
+      "import": "./dist/sessions.js",
+      "default": "./dist/sessions.js"
+    },
     "./coordination": {
       "types": "./dist/coordination.d.ts",
       "import": "./dist/coordination.js",
@@ -115,8 +120,8 @@
     "verify:context-package": "node scripts/verify-context-package.mjs",
     "typecheck": "tsc --noEmit && tsc -p typetests/tsconfig.json && tsc -p examples/tsconfig.json",
     "test": "vitest run",
-    "generate:errors": "tsx scripts/generate-error-docs.mts",
-    "lint:errors": "tsx scripts/check-error-docs.mts",
+    "generate:errors": "tsx --conditions=@ablo/source scripts/generate-error-docs.mts",
+    "lint:errors": "tsx --conditions=@ablo/source scripts/check-error-docs.mts",
     "generate:pricing": "tsx scripts/generate-pricing-docs.mts",
     "lint:pricing": "tsx scripts/check-pricing-docs.mts",
     "generate:openapi": "tsx --conditions=@ablo/source scripts/generate-openapi.mts",
@@ -140,8 +145,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "^0.59.2",
-    "@abloatai/transaction": "^0.59.2",
+    "@abloatai/humans": "^0.60.0",
+    "@abloatai/transaction": "^0.60.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {