@abloatai/ablo 0.36.0 → 0.37.0

package/dist/ai-sdk/index.d.ts

@@ -1,121 +0,0 @@
-/**
- * Ablo + AI SDK tools.
- *
- * The base pattern is intentionally one object all the way down:
- *
- *   1. AI SDK `inputSchema` describes what the model may send.
- *   2. `ablo.<model>.update({ id, data, claim })` performs the write.
- *   3. `claim.description` tells humans and other agents what the tool is doing.
- *
- * ```ts
- * import { tool, streamText } from 'ai';
- * import { z } from 'zod';
- *
- * const renameTask = tool({
- *   description: 'Rename a task.',
- *   inputSchema: z.object({
- *     id: z.string().describe('Task id'),
- *     title: z.string().describe('New task title'),
- *     description: z
- *       .string()
- *       .describe('Why this rename is being made'),
- *   }),
- *   execute: async ({ id, title, description }) => {
- *     await ablo.tasks.update({
- *       id,
- *       data: { title },
- *       wait: 'confirmed',
- *       claim: {
- *         field: 'title',
- *         reason: 'renaming',
- *         description,
- *       },
- *     });
- *
- *     return { id, title };
- *   },
- * });
- *
- * await streamText({
- *   model,
- *   messages,
- *   tools: { renameTask },
- * });
- * ```
- *
- * That is the common case. A claim passed directly to `update` is acquired,
- * attached to the write, and released by the SDK.
- *
- * For multi-step tools, take one handle and release it when the tool is done:
- *
- * ```ts
- * const claim = await ablo.tasks.claim({
- *   id,
- *   reason: 'rewriting',
- *   description: 'Rewriting the task brief before updating follow-up fields.',
- *   ttl: '2m',
- * });
- *
- * try {
- *   await ablo.tasks.update({ id, data: { title }, claim });
- *   await ablo.tasks.update({ id, data: { description: brief }, claim });
- * } finally {
- *   await claim.release();
- * }
- * ```
- *
- * `claim.state`, `claim.queue`, and `claim.reorder` are coordination reads and
- * scheduler controls. They are useful for UI or operators, but normal AI tools
- * should start with `update({ id, data, claim })` or a manual claim handle.
- *
- * `wrapWithMultiplayer` is optional. Use it when the whole model call is scoped
- * to one entity before any tool is chosen; tool implementations stay exactly
- * the same.
- *
- * ## Multi-agent coordination
- *
- * When several agents, or agents and people, write the same row at once, the
- * outcome depends on the write path and the model's conflict policy, not on how
- * capable the model is. The same model silently loses three of four concurrent
- * contributions through a blind whole-row write, yet lands all four through a
- * coordinated one, because a coordinated write returns a signal the model or the
- * runtime can act on. Two rules follow:
- *
- *   1. Surface the signal. A write that swallows the conflict and reports success
- *      is the trap. Every reliable path returns a legible result instead of
- *      overwriting — a rejection leads to a re-read and retry, and a `'claimed'`
- *      result leads the model to try again. A larger model does not fix a silent
- *      write.
- *   2. Back off. Under heavy contention, writers that retry in lock-step simply
- *      collide again. The shared reconcile loop already jitters its backoff, and
- *      any retry you write by hand should too, or it exhausts its budget and drops
- *      a writer.
- *
- * `coordinatedTool` (below) encodes both. Prefer it over a hand-written tool for
- * "save the agent's contribution into the shared row":
- *
- * ```ts
- * import { coordinatedTool } from '@abloatai/ablo/ai-sdk';
- * const saveSection = coordinatedTool(ablo.documents, {
- *   description: 'Save your section into the shared document.',
- *   inputSchema: z.object({ text: z.string() }),
- *   id: () => DOC_ID,
- *   apply: (current, { text }) => ({ content: appendBlock(current.content, text) }),
- *   strategy: 'merge', // 'merge' (default, self-healing) | 'claim' | 'queue'
- * });
- * ```
- *
- * | strategy | writers relate by | on contention | model conflict policy |
- * |----------|-------------------|---------------|------------------------|
- * | `merge`  | accumulate (CAS)  | re-read + re-apply (silent, backed off) | must be `reject` (default) |
- * | `claim`  | mutual exclusion  | returns `{status:'claimed'}` → model retries | any |
- * | `queue`  | FIFO-ish (poll)   | poll-acquire until granted / timeout | any |
- *
- * Note: a model that declares `agentsNotify()` holds a losing write rather than
- * rejecting it, which defeats `'merge'`'s reconcile loop — the loser is dropped
- * instead of retried. Use `agentsReject()` for accumulate semantics, or the
- * `'claim'` or `'queue'` strategy.
- */
-export { coordinationContextMiddleware, type CoordinationContextMiddlewareOptions, type ClaimTarget, } from './coordinationContext.js';
-export { wrapWithMultiplayer, type WrapWithMultiplayerOptions } from './wrap.js';
-export { coordinatedTool, type CoordinationStrategy, type CoordinatedToolOptions, type CoordinatedWriteResult, } from './coordinatedTool.js';

package/dist/ai-sdk/index.js

@@ -1,121 +0,0 @@
-/**
- * Ablo + AI SDK tools.
- *
- * The base pattern is intentionally one object all the way down:
- *
- *   1. AI SDK `inputSchema` describes what the model may send.
- *   2. `ablo.<model>.update({ id, data, claim })` performs the write.
- *   3. `claim.description` tells humans and other agents what the tool is doing.
- *
- * ```ts
- * import { tool, streamText } from 'ai';
- * import { z } from 'zod';
- *
- * const renameTask = tool({
- *   description: 'Rename a task.',
- *   inputSchema: z.object({
- *     id: z.string().describe('Task id'),
- *     title: z.string().describe('New task title'),
- *     description: z
- *       .string()
- *       .describe('Why this rename is being made'),
- *   }),
- *   execute: async ({ id, title, description }) => {
- *     await ablo.tasks.update({
- *       id,
- *       data: { title },
- *       wait: 'confirmed',
- *       claim: {
- *         field: 'title',
- *         reason: 'renaming',
- *         description,
- *       },
- *     });
- *
- *     return { id, title };
- *   },
- * });
- *
- * await streamText({
- *   model,
- *   messages,
- *   tools: { renameTask },
- * });
- * ```
- *
- * That is the common case. A claim passed directly to `update` is acquired,
- * attached to the write, and released by the SDK.
- *
- * For multi-step tools, take one handle and release it when the tool is done:
- *
- * ```ts
- * const claim = await ablo.tasks.claim({
- *   id,
- *   reason: 'rewriting',
- *   description: 'Rewriting the task brief before updating follow-up fields.',
- *   ttl: '2m',
- * });
- *
- * try {
- *   await ablo.tasks.update({ id, data: { title }, claim });
- *   await ablo.tasks.update({ id, data: { description: brief }, claim });
- * } finally {
- *   await claim.release();
- * }
- * ```
- *
- * `claim.state`, `claim.queue`, and `claim.reorder` are coordination reads and
- * scheduler controls. They are useful for UI or operators, but normal AI tools
- * should start with `update({ id, data, claim })` or a manual claim handle.
- *
- * `wrapWithMultiplayer` is optional. Use it when the whole model call is scoped
- * to one entity before any tool is chosen; tool implementations stay exactly
- * the same.
- *
- * ## Multi-agent coordination
- *
- * When several agents, or agents and people, write the same row at once, the
- * outcome depends on the write path and the model's conflict policy, not on how
- * capable the model is. The same model silently loses three of four concurrent
- * contributions through a blind whole-row write, yet lands all four through a
- * coordinated one, because a coordinated write returns a signal the model or the
- * runtime can act on. Two rules follow:
- *
- *   1. Surface the signal. A write that swallows the conflict and reports success
- *      is the trap. Every reliable path returns a legible result instead of
- *      overwriting — a rejection leads to a re-read and retry, and a `'claimed'`
- *      result leads the model to try again. A larger model does not fix a silent
- *      write.
- *   2. Back off. Under heavy contention, writers that retry in lock-step simply
- *      collide again. The shared reconcile loop already jitters its backoff, and
- *      any retry you write by hand should too, or it exhausts its budget and drops
- *      a writer.
- *
- * `coordinatedTool` (below) encodes both. Prefer it over a hand-written tool for
- * "save the agent's contribution into the shared row":
- *
- * ```ts
- * import { coordinatedTool } from '@abloatai/ablo/ai-sdk';
- * const saveSection = coordinatedTool(ablo.documents, {
- *   description: 'Save your section into the shared document.',
- *   inputSchema: z.object({ text: z.string() }),
- *   id: () => DOC_ID,
- *   apply: (current, { text }) => ({ content: appendBlock(current.content, text) }),
- *   strategy: 'merge', // 'merge' (default, self-healing) | 'claim' | 'queue'
- * });
- * ```
- *
- * | strategy | writers relate by | on contention | model conflict policy |
- * |----------|-------------------|---------------|------------------------|
- * | `merge`  | accumulate (CAS)  | re-read + re-apply (silent, backed off) | must be `reject` (default) |
- * | `claim`  | mutual exclusion  | returns `{status:'claimed'}` → model retries | any |
- * | `queue`  | FIFO-ish (poll)   | poll-acquire until granted / timeout | any |
- *
- * Note: a model that declares `agentsNotify()` holds a losing write rather than
- * rejecting it, which defeats `'merge'`'s reconcile loop — the loser is dropped
- * instead of retried. Use `agentsReject()` for accumulate semantics, or the
- * `'claim'` or `'queue'` strategy.
- */
-export { coordinationContextMiddleware, } from './coordinationContext.js';
-export { wrapWithMultiplayer } from './wrap.js';
-export { coordinatedTool, } from './coordinatedTool.js';

package/dist/ai-sdk/wrap.d.ts

@@ -1,65 +0,0 @@
-/**
- * Optional model wrapper for entity-scoped turns.
- *
- * Tool implementations do not change. Keep tools as normal AI SDK tools; use
- * `ablo.<model>.update({ id, data, claim })` inside `execute`. This wrapper is
- * only for the surrounding model call, when the UI already knows "this turn is
- * about report_abc" before the model chooses a tool.
- *
- * It declares one realtime claim while the model is generating and injects a
- * short note if someone else is already working on the same target.
- *
- * ```ts
- * const wrapped = wrapWithMultiplayer({
- *   model: anthropic('claude-opus-4-7'),
- *   agent,
- *   target: { type: 'Report', id: 'report-abc' },
- * });
- *
- * const result = streamText({
- *   model: wrapped,
- *   messages: myMessages,
- *   tools: myTools,
- *   system: mySystem,
- *   // ... anything else the consumer's app needs
- * });
- * ```
- */
-import { wrapLanguageModel } from 'ai';
-import type { LanguageModelV3, LanguageModelV3Middleware } from '@ai-sdk/provider';
-import type { Ablo } from '../client/Ablo.js';
-import type { SchemaRecord } from '../transaction/schema/schema.js';
-import { type ClaimTarget } from './coordinationContext.js';
-export interface WrapWithMultiplayerOptions<R extends SchemaRecord = SchemaRecord> {
-    /** The base language model to wrap. Consumer brings their own. */
-    readonly model: LanguageModelV3;
-    /**
-     * Connected Ablo. Null = pass-through wrap (no broadcast, no read).
-     *
-     * Generic over the schema record (like the two middlewares it composes) so a
-     * caller passing a typed `Ablo<typeof schema>` doesn't have to cast: `Ablo<S>`
-     * and `Ablo<SchemaRecord>` aren't structurally assignable (the widened version
-     * collapses model proxies to an index signature that clashes with the named
-     * methods `ready`/`dispose`/…).
-     */
-    readonly agent: Ablo<R> | null;
-    /** Target entity. Null = pass-through wrap. */
-    readonly target: ClaimTarget | null;
-    /**
-     * Optional claimIds to exclude from the coordination-context
-     * read — typically the caller's own claim if they're composing
-     * multiple wrappings. Most consumers leave this empty.
-     */
-    readonly excludeClaimIds?: readonly string[];
-    /**
-     * Extra middleware to compose. It runs in the order given, nested inside the
-     * multiplayer middleware, so the multiplayer wrap stays the outermost layer.
-     * Use it for caching, observability, or custom transforms that should not
-     * affect the multiplayer signal.
-     *
-     * For full control over ordering, skip this helper and call
-     * `wrapLanguageModel` directly with all the middleware in the order you want.
-     */
-    readonly extraMiddleware?: readonly LanguageModelV3Middleware[];
-}
-export declare function wrapWithMultiplayer<R extends SchemaRecord = SchemaRecord>(options: WrapWithMultiplayerOptions<R>): ReturnType<typeof wrapLanguageModel>;

package/dist/ai-sdk/wrap.js

@@ -1,39 +0,0 @@
-/**
- * Optional model wrapper for entity-scoped turns.
- *
- * Tool implementations do not change. Keep tools as normal AI SDK tools; use
- * `ablo.<model>.update({ id, data, claim })` inside `execute`. This wrapper is
- * only for the surrounding model call, when the UI already knows "this turn is
- * about report_abc" before the model chooses a tool.
- *
- * It declares one realtime claim while the model is generating and injects a
- * short note if someone else is already working on the same target.
- *
- * ```ts
- * const wrapped = wrapWithMultiplayer({
- *   model: anthropic('claude-opus-4-7'),
- *   agent,
- *   target: { type: 'Report', id: 'report-abc' },
- * });
- *
- * const result = streamText({
- *   model: wrapped,
- *   messages: myMessages,
- *   tools: myTools,
- *   system: mySystem,
- *   // ... anything else the consumer's app needs
- * });
- * ```
- */
-import { wrapLanguageModel } from 'ai';
-import { coordinationContextMiddleware, } from './coordinationContext.js';
-export function wrapWithMultiplayer(options) {
-    const { model, agent, target, excludeClaimIds, extraMiddleware } = options;
-    return wrapLanguageModel({
-        model,
-        middleware: [
-            coordinationContextMiddleware({ agent, target, excludeClaimIds }),
-            ...(extraMiddleware ?? []),
-        ],
-    });
-}

package/dist/auth/index.d.ts

@@ -1 +0,0 @@
-export * from '../transaction/auth/index.js';

package/dist/auth/index.js

@@ -1,8 +0,0 @@
-// Moved to @ablo/transaction (ADR 0013 — the settlement core extraction).
-// This shim re-exports it at the original path so in-package importers of
-// `auth/index.js` keep working; rewire to `@ablo/transaction/auth`
-// and delete this shim once the core package is fully wired.
-//
-// Line comments on purpose: tsc copies a leading JSDoc block into the
-// published `.d.ts`, and this note names a package npm has never heard of.
-export * from '../transaction/auth/index.js';

package/dist/batching/index.d.ts

@@ -1,55 +0,0 @@
-/**
- * A small, dependency-free primitive that coalesces work into batches.
- *
- * It accumulates items enqueued close together — the common case being a
- * synchronous burst such as `Promise.all([ a(), b(), c() ])` within one
- * event-loop tick — and dispatches them as a single batch rather than one call
- * each. It is a pure state machine: it stages items on the microtask queue,
- * flushes on size, cost, or time triggers, and applies in-flight backpressure,
- * with no dependency on any data model, storage layer, or network. You supply
- * the dispatch function through {@link BatchSchedulerHooks}.
- *
- * Guarantees:
- *   - each batch is a single `dispatchBatch(items)` call, applied atomically.
- *   - if a dispatch fails, every enqueued promise in that batch rejects with
- *     the same error.
- *   - items dispatch in enqueue order, optionally reordered by `compare` just
- *     before a batch is cut; batches run first-in, first-out under a
- *     `maxInFlight` cap.
- */
-export interface BatchSchedulerOptions<T> {
-    /** Master switch. When false, every `enqueue` dispatches solo immediately. Default true. */
-    readonly enabled?: boolean;
-    /** Coalescing window in ms. `0` (default) → flush on the next microtask (zero added latency). */
-    readonly windowMs?: number;
-    /** Max items per batch before a forced flush. Default 256. */
-    readonly maxBatchSize?: number;
-    /** Max accumulated `costOf` per batch before a forced flush. Default `Infinity` (disabled). */
-    readonly maxBatchCost?: number;
-    /** Per-item cost used by `maxBatchCost` (e.g. serialized bytes). Default `() => 0`. */
-    readonly costOf?: (item: T) => number;
-    /** Max dispatches in flight at once (backpressure). Default 1 → strictly ordered. */
-    readonly maxInFlight?: number;
-}
-export interface BatchSchedulerHooks<T, R> {
-    /** The single dispatch for one batch. One call → atomic at this layer. */
-    dispatchBatch(items: T[]): Promise<R>;
-    /**
-     * Optional ordering applied to the staged items just before a batch is cut —
-     * for example, to send parent rows ahead of the rows that reference them. Omit
-     * for first-in, first-out order. This changes only the order of items within
-     * the dispatched array, not which items share a batch.
-     */
-    compare?(a: T, b: T): number;
-}
-export interface BatchScheduler<T, R> {
-    /** Stage one item; resolves with its batch's dispatch result, or rejects with the batch error. */
-    enqueue(item: T): Promise<R>;
-    /** Stage an item that must dispatch in a batch of its own — for example, one carrying an explicit idempotency key. */
-    enqueueSolo(item: T): Promise<R>;
-    /** Force-flush the pending batch and resolve once everything in flight has settled. */
-    flush(): Promise<void>;
-    /** Stop scheduling and clear timers. Pending/in-flight promises still settle. */
-    dispose(): void;
-}
-export declare function createBatchScheduler<T, R>(hooks: BatchSchedulerHooks<T, R>, options?: BatchSchedulerOptions<T>): BatchScheduler<T, R>;

package/dist/batching/index.js

@@ -1,147 +0,0 @@
-/**
- * A small, dependency-free primitive that coalesces work into batches.
- *
- * It accumulates items enqueued close together — the common case being a
- * synchronous burst such as `Promise.all([ a(), b(), c() ])` within one
- * event-loop tick — and dispatches them as a single batch rather than one call
- * each. It is a pure state machine: it stages items on the microtask queue,
- * flushes on size, cost, or time triggers, and applies in-flight backpressure,
- * with no dependency on any data model, storage layer, or network. You supply
- * the dispatch function through {@link BatchSchedulerHooks}.
- *
- * Guarantees:
- *   - each batch is a single `dispatchBatch(items)` call, applied atomically.
- *   - if a dispatch fails, every enqueued promise in that batch rejects with
- *     the same error.
- *   - items dispatch in enqueue order, optionally reordered by `compare` just
- *     before a batch is cut; batches run first-in, first-out under a
- *     `maxInFlight` cap.
- */
-export function createBatchScheduler(hooks, options) {
-    const enabled = options?.enabled ?? true;
-    const windowMs = options?.windowMs ?? 0;
-    const maxBatchSize = options?.maxBatchSize ?? 256;
-    const maxBatchCost = options?.maxBatchCost ?? Infinity;
-    const costOf = options?.costOf ?? (() => 0);
-    const maxInFlight = options?.maxInFlight ?? 1;
-    let pending = null;
-    let timer = null;
-    let microtaskScheduled = false;
-    const ready = [];
-    let inFlight = 0;
-    let idleWaiters = [];
-    let disposed = false;
-    function scheduleFlush() {
-        if (microtaskScheduled || timer)
-            return;
-        if (windowMs > 0) {
-            timer = setTimeout(() => {
-                timer = null;
-                flushPending();
-            }, windowMs);
-        }
-        else {
-            microtaskScheduled = true;
-            queueMicrotask(() => {
-                microtaskScheduled = false;
-                flushPending();
-            });
-        }
-    }
-    function flushPending() {
-        if (timer) {
-            clearTimeout(timer);
-            timer = null;
-        }
-        microtaskScheduled = false;
-        if (!pending)
-            return;
-        if (hooks.compare)
-            pending.items.sort(hooks.compare);
-        ready.push(pending);
-        pending = null;
-        pump();
-    }
-    function pump() {
-        while (inFlight < maxInFlight && ready.length > 0) {
-            const batch = ready.shift();
-            if (!batch)
-                break;
-            inFlight++;
-            let dispatched;
-            try {
-                dispatched = hooks.dispatchBatch(batch.items);
-            }
-            catch (error) {
-                dispatched = Promise.reject(error);
-            }
-            dispatched
-                .then((result) => {
-                for (const d of batch.deferreds)
-                    d.resolve(result);
-            }, (error) => {
-                for (const d of batch.deferreds)
-                    d.reject(error);
-            })
-                .finally(() => {
-                inFlight--;
-                pump();
-                notifyIdleIfDrained();
-            });
-        }
-    }
-    function notifyIdleIfDrained() {
-        if (inFlight === 0 && ready.length === 0 && idleWaiters.length > 0) {
-            const waiters = idleWaiters;
-            idleWaiters = [];
-            for (const w of waiters)
-                w();
-        }
-    }
-    function enqueueSolo(item) {
-        return new Promise((resolve, reject) => {
-            ready.push({ items: [item], deferreds: [{ resolve, reject }], cost: costOf(item) });
-            pump();
-        });
-    }
-    function enqueue(item) {
-        if (disposed)
-            return Promise.reject(new Error('batch scheduler disposed'));
-        if (!enabled)
-            return enqueueSolo(item);
-        const cost = costOf(item);
-        return new Promise((resolve, reject) => {
-            const deferred = { resolve, reject };
-            // Rollover: if appending would blow a cap, flush the current batch first.
-            if (pending && (pending.items.length + 1 > maxBatchSize || pending.cost + cost > maxBatchCost)) {
-                flushPending();
-            }
-            if (!pending)
-                pending = { items: [], deferreds: [], cost: 0 };
-            pending.items.push(item);
-            pending.deferreds.push(deferred);
-            pending.cost += cost;
-            if (pending.items.length >= maxBatchSize || pending.cost >= maxBatchCost) {
-                flushPending();
-            }
-            else {
-                scheduleFlush();
-            }
-        });
-    }
-    async function flush() {
-        flushPending();
-        while (ready.length > 0 || inFlight > 0) {
-            await new Promise((resolve) => idleWaiters.push(resolve));
-        }
-    }
-    function dispose() {
-        disposed = true;
-        if (timer) {
-            clearTimeout(timer);
-            timer = null;
-        }
-        microtaskScheduled = false;
-    }
-    return { enqueue, enqueueSolo, flush, dispose };
-}