@abloatai/ablo 0.18.0 → 0.19.0

package/dist/types/streams.d.ts

@@ -100,7 +100,7 @@ export interface ContextChange {
  * `range`, `field`, and `meta` are generic coordination hints for
  * products like code editors, document editors, and design tools.
  */
-export interface EntityRef {
+export interface ClaimTarget {
     readonly type: string;
     readonly id: string;
     readonly path?: string;
@@ -110,11 +110,11 @@ export interface EntityRef {
 }
 /**
  * A pointer to one entity the participant is acting on. Either a
- * typed `EntityRef` (`{ type, id, ... }`), or a tuple
+ * typed `ClaimTarget` (`{ type, id, ... }`), or a tuple
  * `['Clause', 'cl_3']` for ergonomic inline use. The verb methods
  * below accept both.
  */
-export type PresenceTarget = EntityRef | readonly [type: string, id: string];
+export type PresenceTarget = ClaimTarget | readonly [type: string, id: string];
 /**
  * Reactive livestream of what every multiplayer participant is doing.
  * Every participant gets one; it's always on, always current.
@@ -336,27 +336,12 @@ export interface ClaimOptions extends ClaimLeaseOptions {
     readonly queue?: boolean;
 }
 export interface ClaimStream {
-    /**
-     * Claim an exclusive claim on a target. Returns a handle — call
-     * `.revoke()` to cancel, let it expire via TTL, or use `await using`
-     * (TC39 explicit resource management) to auto-revoke on scope exit.
-     *
-     * Server rejects via `claim_rejected` when another participant
-     * already holds a claim on the same target. Default `reason` is
-     * `'editing'`; pass `{reason: 'writing'}` (or any string) to override.
-     *
-     * The frame ships on the open WS immediately. One method, one shape —
-     * the verb shortcuts (`editing`, `writing`, `announce`) and the
-     * scoped `claim(reason, opts)` overload were collapsed into this
-     * single primitive.
-     */
-    claim(target: PresenceTarget, opts?: ClaimOptions): ClaimHandle;
     /**
      * Reactive view of every other participant's active claims.
      * Reads return the current snapshot; pair with `subscribe(...)`
      * below to get notified on change.
      */
-    readonly others: ReadonlyArray<ActiveClaim>;
+    readonly others: ReadonlyArray<Claim>;
     /**
      * Reactive view of the wait queue on one target — the FIFO line of
      * `status: 'queued'` claims behind the current holder, each with its
@@ -425,7 +410,7 @@ export interface ClaimStream {
      * }
      * ```
      */
-    [Symbol.asyncIterator](): AsyncIterableIterator<ReadonlyArray<ActiveClaim>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<ReadonlyArray<Claim>>;
 }
 /**
  * You LOST an claim you were HOLDING — distinct from `ClaimRejection` (a
@@ -452,95 +437,6 @@ export interface ClaimLost {
         readonly meta?: Record<string, unknown>;
     };
 }
-export interface ClaimDeclaration {
-    readonly target: EntityRef;
-    /** Human-readable reason — "rewriting title" / "restyling chart". */
-    readonly reason: string;
-    /**
-     * Seconds remaining until the server auto-expires this claim. An OUTPUT
-     * field carrying a concrete countdown, so it's a plain `number` — distinct
-     * from the input `ttl: Duration` (`'3m'`) you pass when announcing. Computed
-     * from `expiresAt - now`.
-     */
-    readonly ttlSeconds?: number;
-}
-/**
- * Handle returned from `announce(...)` / `analyzing(...)` / etc.
- *
- * Implements `Symbol.asyncDispose` so callers can write:
- *
- * ```ts
- * {
- *   await using work = participant.claims.analyzing(clause, { ttl: '3m' });
- *   // ... do the work; claim auto-revokes when the block exits
- * }
- * ```
- */
-/**
- * THE one claim handle. Returned by every claim door — the typed
- * `ablo.<model>.claim({ id })` (rich: `data`/`readAt`/`target` populated) and
- * the low-level `participant.claims.claim()` lease (minimal: `claimId` +
- * `revoke`/`release`). Row-level fields are optional precisely because the
- * low-level lease has no row snapshot; the model door fills them in.
- *
- * Implements `Symbol.asyncDispose` so callers can `await using claim = ...`
- * and have it auto-release on scope exit.
- */
-export interface ClaimHandle<T = Record<string, unknown>> extends AsyncDisposable {
-    readonly object: 'claim';
-    readonly claimId: string;
-    /**
-     * True when the grant came AFTER waiting in the server's FIFO line
-     * (`claim_granted`) — the authoritative "the row may have changed under us"
-     * signal. Absent for an immediate grant or a non-queued lease.
-     */
-    readonly waited?: boolean;
-    /**
-     * Sync watermark of the held snapshot (`data` was read at this stamp). Writes
-     * carrying the handle use it as the `readAt` stale guard. Present for
-     * model-scoped claims; absent for low-level leases.
-     */
-    readonly readAt?: number;
-    readonly target: {
-        readonly model: string;
-        readonly id: string;
-        readonly field?: string;
-        readonly path?: string;
-        readonly range?: TargetRange;
-        readonly meta?: Record<string, unknown>;
-    };
-    /**
-     * The human-readable phase this claim represents — `'editing'`, `'writing'`,
-     * `'forecasting'`. The SAME word on every claim surface (inputs and outputs);
-     * distinct from the CRUD operation (`CommitOperationInput.action`). Defaults
-     * to `'editing'`. Serialized on the wire as `action`.
-     */
-    readonly reason: string;
-    readonly description?: string;
-    /** Row snapshot — populated by `ablo.<model>.claim`; absent on low-level leases. */
-    readonly data?: T;
-    release(): Promise<void>;
-    revoke(): void;
-}
-export interface ActiveClaim extends ClaimDeclaration {
-    readonly id: string;
-    readonly heldBy: string;
-    /**
-     * Whether the holding participant is a user (session), an agent, or a
-     * system actor. First-class field so UIs can style "agent editing X"
-     * differently from "user editing X" without string-parsing `heldBy`.
-     * Canonical `'user' | 'agent' | 'system'` — the presence/claim stream
-     * derives the value from the boolean `isAgent` wire flag (so it produces
-     * only `'user'`/`'agent'`), but the type stays the full union it shares
-     * with the HTTP claim surface and lease store.
-     */
-    readonly participantKind: ParticipantKind;
-    readonly description?: string;
-    /** Epoch-ms the claim was announced. */
-    readonly announcedAt: number;
-    /** Epoch-ms the server auto-expires it. */
-    readonly expiresAt: number;
-}
 /**
  * Every lifecycle state of a coordination claim, in one enum.
  * `active` = the current holder (the lock). `queued` = waiting in the FIFO
@@ -554,44 +450,70 @@ export interface ClaimWaitOptions {
     readonly pollInterval?: number;
     readonly signal?: AbortSignal;
 }
-/**
- * The coordination state of one entity. Self-describing on the wire via
- * `object: 'claim'`. Existence with `status: 'active'` *is* the lock;
- * the fields *are* the awareness ("agent X is editing this until Y").
- *
- * Deliberately omits a Stripe-style `next_action`: a contender's only
- * response is "wait until free, then re-read", and the runtime performs
- * that uniformly — `claim` serializes behind the holder via the server
- * FIFO queue (or low-level `claims.waitFor` to wait without claiming), and the
- * stale-context guard forces the re-read. Encoding a constant instruction
- * the engine always takes would be the kind of ceremony this object exists
- * to remove.
- */
-export interface Claim {
+export interface Claim<T = Record<string, unknown>> {
     readonly object: 'claim';
+    /** This claim's id. */
     readonly id: string;
-    readonly status: ClaimStatus;
+    /**
+     * Lifecycle state. `active` = the holder (the lock); `queued` = waiting in
+     * the FIFO line (carries `position`). Optional on shapes derived from a
+     * presence frame that don't carry it — a present entry is `active` by
+     * construction.
+     */
+    readonly status?: ClaimStatus;
     /** What is being coordinated. */
-    readonly target: EntityRef;
-    /** Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. The same
-     *  field on every claim surface; distinct from the CRUD operation. Serialized
-     *  on the wire as `action`. */
+    readonly target: ClaimTarget;
+    /**
+     * Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. The same
+     * field on every claim surface; distinct from the CRUD operation. Defaults to
+     * `'editing'`.
+     */
     readonly reason: string;
     /** Peer-visible explanation of the work being performed. */
     readonly description?: string;
-    /** Participant holding it. */
-    readonly heldBy: string;
-    readonly participantKind: ParticipantKind;
+    /** Participant holding it. Absent on a handle you hold for yourself. */
+    readonly heldBy?: string;
     /**
-     * Epoch-ms the holder opened it. Optional until the lease wire carries
-     * it — derived shapes (e.g. mapped from a presence frame) may omit it.
+     * Whether the holder is a user (session), agent, or system actor — so UIs
+     * style "agent editing X" vs "user editing X" without string-parsing
+     * `heldBy`. Present on observed claims; absent on your own fresh handle.
      */
+    readonly participantKind?: ParticipantKind;
+    /** Epoch-ms the holder opened it. */
     readonly createdAt?: number;
     /** Epoch-ms the server auto-expires it if the holder doesn't finish. */
-    readonly expiresAt: number;
+    readonly expiresAt?: number;
+    /**
+     * Seconds remaining until auto-expiry — an OUTPUT countdown (plain `number`),
+     * distinct from the input `ttl: Duration` (`'3m'`) you pass when claiming.
+     */
+    readonly ttlSeconds?: number;
     /**
      * 0-based place in the FIFO line — present only when `status: 'queued'`
-     * (`0` = next in line behind the holder). Absent for the active holder.
+     * (`0` = next behind the holder). Absent for the active holder.
      */
     readonly position?: number;
+    /**
+     * True when the grant came AFTER waiting in the server's FIFO line
+     * (`claim_granted`) — the authoritative "the row may have changed under us"
+     * signal. Absent for an immediate (uncontended) grant.
+     */
+    readonly waited?: boolean;
+    /**
+     * Sync watermark of the held snapshot (`data` was read at this stamp). Writes
+     * carrying the claim use it as the `readAt` stale guard. Present on a claim
+     * you hold.
+     */
+    readonly readAt?: number;
+    /** Row snapshot under the lease — present on a claim you hold. */
+    readonly data?: T;
+    /**
+     * Release the lease. Present only on a claim you HOLD (returned by
+     * `ablo.<model>.claim`); absent on observed peer claims.
+     */
+    release?(): Promise<void>;
+    /** Synchronously abandon the lease. Present only on a claim you hold. */
+    revoke?(): void;
+    /** Auto-release on `await using` scope exit. Present only on a held claim. */
+    [Symbol.asyncDispose]?(): PromiseLike<void>;
 }

package/docs/coordination.md

@@ -25,6 +25,22 @@ one answer to "how do two agents not clobber each other" — then covers the
 (`claim` · `claim.state` · `claim.queue` · `claim.release` · [writing under a
 claim](#writing-under-a-claim)), and the [errors](#errors) you can catch.
 
+> **Before anything else: one identity per agent.** Coordination excludes
+> *participants*, and a participant **is the key**, not the client object. The
+> server derives identity from the credential's scope — so **N clients sharing
+> one `sk_`/`ek_` are one participant**: they all see the same `heldBy`, never
+> queue behind each other, and a "second" claimer silently re-takes the lease it
+> already holds (no mutual exclusion). To get real per-agent exclusion, mint a
+> **distinct scoped `rk_` per agent** and bind a client to it:
+>
+> ```ts
+> const { token } = await ablo.sessions.create({ agent: { id: `agent-${i}` } }); // rk_
+> const agent = Ablo({ schema, apiKey: token }); // this agent's own participant
+> ```
+>
+> Now `agent-0` holds while `agent-1`/`agent-2` queue in FIFO order and drain in
+> turn. See [sessions](./sessions.md#agent-sessions-rk_) for the minting flow.
+
 ---
 
 ## The model — three layers, one decision

package/docs/debugging.md

@@ -0,0 +1,194 @@
+# Debugging & Logs
+
+By default the SDK is quiet — it logs only warnings and errors. When you're building a human + agent flow and want to *see* the coordination happen (who claimed what, who's waiting in line, who got preempted), turn on Ablo's diagnostic logging. Every line is prefixed `[Ablo]` so it's obvious which output is ours in a console full of other tools.
+
+## Turn it on
+
+```ts
+import Ablo from '@abloatai/ablo';
+import { schema } from './ablo/schema';
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, debug: true });
+```
+
+`debug: true` is the simple switch. For finer control use `logLevel`, or set it without touching code via the `ABLO_LOG_LEVEL` environment variable.
+
+```ts
+Ablo({ schema, apiKey })                       // quiet — warnings + errors only (default)
+Ablo({ schema, apiKey, debug: true })          // everything (coordination + lifecycle)
+Ablo({ schema, apiKey, logLevel: 'info' })     // coordination + connection, no per-model noise
+```
+
+```bash
+ABLO_LOG_LEVEL=debug npm run dev               # same, from the environment
+```
+
+### Levels
+
+| Level | What it shows |
+|---|---|
+| `silent` | nothing |
+| `error` | failures only |
+| `warn` | **default** — warnings + errors |
+| `info` | the above + the **coordination trace** (claims, grants, queueing) + connection state |
+| `debug` | the above + internal lifecycle (per-model registration, store hydration) — the full firehose |
+
+Precedence: an explicit `logLevel` wins, then `debug: true` (⇒ `debug`), then `ABLO_LOG_LEVEL`, then the `warn` default. `debug: false` (or omitting it) just means "don't raise the level."
+
+> For watching coordination, **`logLevel: 'info'` is the sweet spot** — you get the claim trace without the per-model registration chatter that `debug` adds.
+
+## What you'll see — the coordination trace
+
+These lines (all at `info`) let you watch the human + agent handover you built:
+
+```
+[Ablo] claim: requesting documents:doc_42 for "editing" (will queue if contended)
+[Ablo] claim: queued for documents:doc_42 — position 2 of 3, waiting
+[Ablo] claim: granted 7f3c… — your turn (waited in queue)
+[Ablo] claim: rejected documents:doc_42 — held by agent_writer
+[Ablo] claim: lost documents:doc_42 (preempted or expired)
+[Ablo] claim: released documents:doc_42
+```
+
+Read it as the lifecycle of one claim:
+
+- **`requesting`** — your code (or an agent) called `ablo.<model>.claim(...)`. `(will queue if contended)` appears when you passed `{ queue: true }`.
+- **`queued … position N of M`** — the row was held, so you're waiting in the FIFO line. This is the "an agent is waiting behind a claim" moment; it re-logs only when your position changes, so you can watch it advance.
+- **`granted … your turn`** — you reached the head of the line; the lease is now yours and the row may have changed while you waited.
+- **`rejected … held by <who>`** — your claim was refused because someone else holds it (and the model's policy didn't let you in).
+- **`lost`** — you held the lease and it was taken (preempted by a higher-priority writer, or it expired).
+- **`released`** — you (or `await using`'s scope exit) gave the lease back.
+
+## Where the logs run
+
+The coordination trace and the proactive credential refresh run **in the browser** (and any client that holds a live socket) — that's where the human + agent activity is. Server-side code that mints credentials or does one-shot reads won't emit the trace; it has no live session to narrate.
+
+## Bring your own logger
+
+Pass a `logger` to route Ablo's output into your own logging stack (Pino, Sentry breadcrumbs, etc.). A custom logger bypasses `debug`/`logLevel` entirely — you decide what to do with each level.
+
+```ts
+Ablo({
+  schema,
+  apiKey,
+  logger: {
+    debug: (...a) => {},
+    info: (...a) => myLogger.info({ ablo: a }),
+    warn: (...a) => myLogger.warn({ ablo: a }),
+    error: (...a) => myLogger.error({ ablo: a }),
+  },
+});
+```
+
+## Read the coordination in code — the activity log
+
+The console trace above is for *you*, at a terminal. To put the same activity **inside your app** — an activity feed, a "who's editing" badge, a Sentry breadcrumb trail — read it programmatically. Same events, three layers; pick by audience:
+
+| Layer | You get | Best for |
+|---|---|---|
+| `logger` (above) | `[Ablo]` text lines | watching a terminal |
+| `observability` | typed `ClaimEvent` / `ConflictEvent` objects | dashboards, alerting (Sentry / Datadog / OTel) |
+| `ClaimLog` | an ordered, **reactive** list of both | rendering an activity feed on a page |
+
+### The events
+
+Every claim state change is a `ClaimEvent`; every notify-instead-of-abort stale write (a write that succeeded but whose premise had moved) is a `ConflictEvent`:
+
+```ts
+interface ClaimEvent {
+  phase: 'acquired' | 'queued' | 'granted' | 'lost' | 'rejected' | 'expired';
+  model?: string; id?: string; field?: string;          // the claimed row
+  actor?: string; participantKind?: 'user' | 'agent' | 'system';
+  position?: number;   // FIFO position, when queued
+  reason?: string;     // why, on rejected
+  claimId?: string;
+}
+
+interface ConflictEvent {
+  clientTxId: string;
+  rows: { model: string; id: string; fields: string[]; writtenBy?: 'user' | 'agent' | 'system' }[];
+}
+```
+
+`phase` is past-tense — the state the claim just entered — and maps one-to-one to what arrives on the wire.
+
+### Collect them — `ClaimLog`
+
+`ClaimLog` records both into an ordered list. Hand it to `observability`, then read it back:
+
+```ts
+import Ablo, { ClaimLog } from '@abloatai/ablo';
+
+const log = new ClaimLog();
+const ablo = Ablo({ schema, apiKey, observability: log });
+
+// …run the agents…
+console.log(`${log}`);   // a printable, ⚠-marked timeline
+log.entries;             // ClaimLogEntry[] — every event, in order, with a `.line`
+log.collisions();        // just the rejected/lost claims + stale writes
+```
+
+It's also the simplest way to **assert** coordination in a test — no log scraping:
+
+```ts
+expect(log.collisions()).toHaveLength(0);   // no one stepped on anyone
+```
+
+### Show it on a page — reactive
+
+`ClaimLog.onChange` fires on every event and returns an unsubscribe — the exact shape `useSyncExternalStore` wants, so a live feed is a few lines:
+
+```tsx
+import { useSyncExternalStore } from 'react';
+import { ClaimLog } from '@abloatai/ablo';
+
+function ActivityFeed({ log }: { log: ClaimLog }) {
+  const entries = useSyncExternalStore(log.onChange, () => log.entries);
+  return (
+    <ul>
+      {entries.map((e) => (
+        <li key={e.seq} className={e.collision ? 'text-amber-600' : undefined}>{e.line}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+> `ClaimLog` lives in browser memory: it starts empty on load and shows events that arrive while mounted. For a feed that survives reload, persist `entries` yourself — but for a live coordination panel, the in-memory log is exactly right.
+
+For **"who holds *this* row right now"** (a badge, not a feed), don't use `ClaimLog` — read the reactive claim state directly. It re-renders on change with no extra wiring:
+
+```tsx
+const holder = useAblo((ablo) => ablo.documents.claim.state({ id }));   // Claim | null
+```
+
+See [React](./react.md) and [Coordination](./coordination.md) for the claim-read APIs.
+
+### Route to your own backend
+
+`ClaimLog` is one implementation of the `observability` slot. To push events into Sentry, Datadog, or OpenTelemetry instead, spread `noopObservability` and override just the two coordination hooks:
+
+```ts
+import Ablo, { noopObservability } from '@abloatai/ablo';
+
+const ablo = Ablo({
+  schema, apiKey,
+  observability: {
+    ...noopObservability,
+    captureClaim: (e) => {
+      if (e.phase === 'rejected') Sentry.captureMessage(`claim blocked: ${e.model}/${e.id} by ${e.actor}`);
+    },
+    captureConflict: (e) => Sentry.captureMessage(`stale write tx ${e.clientTxId} on ${e.rows.length} row(s)`),
+  },
+});
+```
+
+## Errors
+
+Ablo's thrown errors are typed and self-describing — `String(err)` (or logging it) yields one clean line, never a stack dump:
+
+```
+AbloValidationError [model_required_field_missing]: A required field was absent. (see https://docs.abloatai.com/errors#model_required_field_missing) [request_id: req_8Fk2aQ]
+```
+
+Branch on `err.code` (stable) — never on the message (rewordable). See [Client Behavior](./client-behavior.md) for the full error model and which codes are safe to retry.

package/docs/index.md

@@ -48,6 +48,7 @@ Three things stay true no matter how you use Ablo:
 - [Interaction Model](./interaction-model.md) — The schema, claim, update, confirmation loop.
 - [API Reference](./api.md) — Model-by-model method shape.
 - [Client Behavior](./client-behavior.md) — Options, errors, retries, timeouts, and imports.
+- [Debugging & Logs](./debugging.md) — Turn on the `[Ablo]` coordination trace (`debug` / `logLevel`) to watch claims, queueing, and grants while you build — or read the same activity in code via `ClaimLog` to render an activity feed.
 - [Connect Your Database](./data-sources.md) — Keep canonical rows in your app database without giving Ablo database credentials.
 - [React](./react.md) — Provider, hooks, and reactive reads for React apps.
 - [API Keys](./api-keys.md) — Bearer tokens for the public API.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",

package/dist/ai-sdk/claim-broadcast.d.ts

@@ -1,83 +0,0 @@
-/**
- * Claim broadcast middleware — wraps a language model so the agent
- * declares "I'm about to edit entity X" over the sync engine's
- * claim primitive at stream start, and abandons the claim at
- * stream end.
- *
- * Cross-cutting by design — composes via the AI SDK's
- * `wrapLanguageModel`. Same middleware works for every chat
- * surface, and for non-chat agent loops that share the AI SDK's
- * middleware interface (workers, MCP tools, autonomous loops).
- *
- * Open-source-clean: depends only on `@ai-sdk/provider` types and
- * the package's own `SyncAgent`. No app-specific assumptions —
- * Ablo's web app uses this, but so can any consumer of `@abloatai/ablo`.
- *
- * Cost: one WS frame at stream start (`claim_begin`), one at end
- * (`claim_abandon`). No DB I/O, no extra LLM tokens.
- */
-import type { LanguageModelV3Middleware } from '@ai-sdk/provider';
-import type { Ablo } from '../client/Ablo.js';
-import type { SchemaRecord } from '../schema/schema.js';
-/**
- * Target entity for the claim broadcast.
- *
- * `entityType` is a free-form string — convention is the schema's
- * typename (e.g. `'SlideDeck'`, `'Task'`, `'Matter'`) so peers can
- * filter consistently. The wire format treats it opaquely.
- */
-export interface ClaimTarget {
-    readonly entityType: string;
-    readonly entityId: string;
-    /** Optional path for file/document-like targets. */
-    readonly path?: string;
-    /** Optional line/column range for partial-entity coordination. */
-    readonly range?: {
-        readonly startLine: number;
-        readonly endLine: number;
-        readonly startColumn?: number;
-        readonly endColumn?: number;
-    };
-    /**
-     * Optional sub-field within the entity. Useful when the agent
-     * knows it's only editing a specific field — peers can filter
-     * on the field too.
-     */
-    readonly field?: string;
-    /** App-defined structured metadata. Opaque to the core SDK. */
-    readonly meta?: Record<string, unknown>;
-    /**
-     * Hint for the server-side TTL on the claim. Caps at 10 minutes
-     * server-side; default 60s — typical chat turn.
-     */
-    readonly estimatedMs?: number;
-}
-export interface ClaimBroadcastMiddlewareOptions<R extends SchemaRecord = SchemaRecord> {
-    /** Connected Ablo. Null disables the middleware (no-op). */
-    readonly agent: Ablo<R> | null;
-    /** Target entity. Null skips the broadcast (purely conversational). */
-    readonly target: ClaimTarget | null;
-    /**
-     * Human-readable phase describing what the agent is doing. Convention:
-     * `'edit'`, `'read'`, `'review'`, `'generate'`. Default `'edit'`. The same
-     * `reason` field used on every claim surface.
-     */
-    readonly reason?: string;
-    /**
-     * Peer-visible explanation of the specific work this model call is about to
-     * perform. Surfaces to other agents through `ActiveClaim.description`.
-     */
-    readonly description?: string;
-}
-/**
- * Build the middleware. When `agent` or `target` is null, returns a
- * pass-through — keeps call sites unconditional regardless of
- * whether the surface has an entity in scope.
- *
- * Generic over the schema record so callers passing
- * `Ablo<typeof schema>` don't have to widen — `Ablo<S>` and
- * `Ablo<SchemaRecord>` are structurally non-compatible because the
- * widened version collapses model proxies to an index signature
- * that clashes with the named methods (`ready`, `dispose`, etc.).
- */
-export declare function claimBroadcastMiddleware<R extends SchemaRecord = SchemaRecord>(options: ClaimBroadcastMiddlewareOptions<R>): LanguageModelV3Middleware;

package/dist/ai-sdk/claim-broadcast.js

@@ -1,79 +0,0 @@
-/**
- * Claim broadcast middleware — wraps a language model so the agent
- * declares "I'm about to edit entity X" over the sync engine's
- * claim primitive at stream start, and abandons the claim at
- * stream end.
- *
- * Cross-cutting by design — composes via the AI SDK's
- * `wrapLanguageModel`. Same middleware works for every chat
- * surface, and for non-chat agent loops that share the AI SDK's
- * middleware interface (workers, MCP tools, autonomous loops).
- *
- * Open-source-clean: depends only on `@ai-sdk/provider` types and
- * the package's own `SyncAgent`. No app-specific assumptions —
- * Ablo's web app uses this, but so can any consumer of `@abloatai/ablo`.
- *
- * Cost: one WS frame at stream start (`claim_begin`), one at end
- * (`claim_abandon`). No DB I/O, no extra LLM tokens.
- */
-/**
- * Build the middleware. When `agent` or `target` is null, returns a
- * pass-through — keeps call sites unconditional regardless of
- * whether the surface has an entity in scope.
- *
- * Generic over the schema record so callers passing
- * `Ablo<typeof schema>` don't have to widen — `Ablo<S>` and
- * `Ablo<SchemaRecord>` are structurally non-compatible because the
- * widened version collapses model proxies to an index signature
- * that clashes with the named methods (`ready`, `dispose`, etc.).
- */
-export function claimBroadcastMiddleware(options) {
-    const { agent, target } = options;
-    const reason = options.reason ?? 'edit';
-    const description = options.description;
-    const openClaim = () => {
-        if (!agent || !target)
-            return null;
-        return agent.claims.claim({
-            type: target.entityType,
-            id: target.entityId,
-            path: target.path,
-            range: target.range,
-            field: target.field,
-            meta: target.meta,
-        }, {
-            reason,
-            description,
-            ttl: target.estimatedMs ?? 60_000,
-        });
-    };
-    return {
-        specificationVersion: 'v3',
-        // The AI SDK's middleware contract passes a no-arg `doStream` /
-        // `doGenerate` thunk — params have already been transformed by
-        // any earlier `transformParams` middleware in the chain. We
-        // open the claim, call the inner, abandon when the inner
-        // resolves (or rejects).
-        async wrapStream({ doStream }) {
-            const handle = openClaim();
-            try {
-                return await doStream();
-            }
-            finally {
-                // Always abandon — even on error. The server's TTL would
-                // eventually clean up regardless, but explicit release means
-                // peers see the claim drop the moment generation completes.
-                handle?.revoke();
-            }
-        },
-        async wrapGenerate({ doGenerate }) {
-            const handle = openClaim();
-            try {
-                return await doGenerate();
-            }
-            finally {
-                handle?.revoke();
-            }
-        },
-    };
-}