@abloatai/ablo 0.26.0 → 0.27.0

package/dist/agent/types.d.ts

@@ -1,37 +1,32 @@
 /**
- * Agent-SDK abstractions. The engine's data vocabulary
- * (`Peer`, `Activity`, `Claim`, `ActiveClaim`,
- * `PresenceUpdatePayload`, `PresenceKind`) lives in
- * `../types/streams.ts`. This file holds only the bits that are
- * specific to the agent module: the `PresenceAnnouncer` abstraction
- * (transport-agnostic announce contract) and `AgentContext` (the AI
- * SDK `experimental_context` bag).
+ * Types specific to running AI agents. The shared data vocabulary — `Peer`,
+ * {@link Activity}, `Claim`, `ActiveClaim`, `PresenceUpdatePayload`, and
+ * `PresenceKind` — lives in the streams module. This file adds only the two
+ * pieces the agent layer needs on top of it: {@link PresenceAnnouncer}, a
+ * transport-agnostic way to announce presence, and {@link AgentContext}, the bag
+ * of ambient state passed to AI SDK tools.
  */
 import type { Activity } from '../types/streams.js';
 /**
- * A minimal interface for announcing presence — abstract over WebSocket
- * (`Ablo({kind: 'agent'})`) and REST (`Agent`). Both
- * implementations satisfy this, so higher-level code can depend on it
- * without caring about transport.
+ * A minimal interface for announcing an agent's presence, independent of how it
+ * connects. Both the WebSocket-based agent client and the REST-based agent
+ * implement it, so higher-level code can depend on this interface without caring
+ * which transport is in use.
  */
 export interface PresenceAnnouncer {
     announce(status: 'online' | 'away' | 'offline', activity?: Activity): Promise<void>;
 }
 /**
- * Ambient context threaded into AI SDK tools via `experimental_context`.
+ * The ambient state passed to AI SDK tools through the AI SDK's
+ * `experimental_context`. Build one {@link AgentContext} per agent invocation and
+ * pass it as `experimental_context`; each tool's `execute` function then reads
+ * what it needs from `options.experimental_context` rather than closing over
+ * shared module state.
  *
- * The pattern: the caller constructs an AgentContext once per agent
- * invocation and passes it as `experimental_context`. Each tool's
- * `execute` function extracts what it needs from
- * `options.experimental_context` instead of closing over module-level
- * state.
- *
- * Benefits over closure-based tool wiring:
- * - Tools are framework-agnostic module exports (portable across agents)
- * - The context is typed in one place, not scattered across closures
- * - New tools can access any field without changing tool signatures
- *
- * Ported from the vercel-labs/open-agents pattern.
+ * Passing context this way, rather than capturing it in each tool's closure,
+ * keeps tools as plain module exports that any agent can reuse, types the context
+ * in one place, and lets a new tool read any field without changing its
+ * signature.
  *
  * ```ts
  * import { generateText, tool } from 'ai';
@@ -54,20 +49,20 @@ export interface PresenceAnnouncer {
  * });
  * ```
  *
- * Consumers can extend AgentContext via module augmentation or by
- * intersecting with their own context type.
+ * Extend {@link AgentContext} with your own fields through module augmentation or
+ * by intersecting it with your own context type.
  */
 export interface AgentContext {
-    /** Presence / freshness / AI SDK hook primitives. Required. */
+    /** Announces presence and checks whether an entity has changed since a given time. Required. */
     perception: PresenceAnnouncer & {
         checkFreshness?: (entityType: string, entityId: string, lastSeenAt: number) => Promise<unknown>;
     };
-    /** Organization scope for all operations. */
+    /** The organization every operation is scoped to. */
     organizationId?: string;
-    /** User or agent identifier — format: "agent:<id>" for agents. */
+    /** Identifier for the user or agent. Agents use the form `agent:<id>`. */
     userId?: string;
-    /** Sync groups the agent belongs to. */
+    /** The sync groups this agent belongs to. */
     syncGroups?: string[];
-    /** Allow extension with product-specific fields. */
+    /** Room for your own product-specific fields. */
     [key: string]: unknown;
 }

package/dist/agent/types.js

@@ -1,10 +1,9 @@
 /**
- * Agent-SDK abstractions. The engine's data vocabulary
- * (`Peer`, `Activity`, `Claim`, `ActiveClaim`,
- * `PresenceUpdatePayload`, `PresenceKind`) lives in
- * `../types/streams.ts`. This file holds only the bits that are
- * specific to the agent module: the `PresenceAnnouncer` abstraction
- * (transport-agnostic announce contract) and `AgentContext` (the AI
- * SDK `experimental_context` bag).
+ * Types specific to running AI agents. The shared data vocabulary — `Peer`,
+ * {@link Activity}, `Claim`, `ActiveClaim`, `PresenceUpdatePayload`, and
+ * `PresenceKind` — lives in the streams module. This file adds only the two
+ * pieces the agent layer needs on top of it: {@link PresenceAnnouncer}, a
+ * transport-agnostic way to announce presence, and {@link AgentContext}, the bag
+ * of ambient state passed to AI SDK tools.
  */
 export {};

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

@@ -0,0 +1,108 @@
+/**
+ * Turns a write to one of your models into a Vercel AI SDK tool that handles
+ * multi-agent coordination for you, so an agent can contribute to shared state
+ * without silently overwriting another writer's concurrent change.
+ *
+ * The lower-level approach is to write your own `tool()` and call
+ * `ablo.<model>.update({ id, data, claim })` inside its `execute` — the right
+ * amount of control for a bespoke tool. This helper covers the common case
+ * instead: the agent produced some content and you want to save it into a shared
+ * row, without re-deriving optimistic concurrency each time. You declare the
+ * write:
+ *
+ * ```ts
+ * import { coordinatedTool } from '@abloatai/ablo/ai-sdk';
+ * import { z } from 'zod';
+ *
+ * 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'  ← the default
+ * });
+ *
+ * await streamText({ model, messages, tools: { saveSection } });
+ * ```
+ *
+ * The {@link CoordinatedToolOptions.apply} function is the whole API: a pure
+ * function from the freshest row and the tool input to a patch, in the same
+ * spirit as a functional state update. Everything beneath it — reading the latest
+ * row, the compare-and-swap, backing off between retries, and releasing claims —
+ * is the runtime's job.
+ *
+ * ## Strategies
+ *
+ * Choose a strategy by how you want concurrent writers to relate. Each is
+ * designed to converge under many agents writing at once.
+ *
+ * - `'merge'` (the default) delegates to the functional update
+ *   `ablo.<model>.update(id, current => apply(current, input))`. The runtime
+ *   re-reads and re-applies `apply` on top of every concurrent write, backing off
+ *   between rounds, so many agents accumulate into one row and the model never
+ *   sees a conflict. This requires the model's agent conflict policy to be
+ *   `reject` (the default, or `agentsReject()`). A model that declares
+ *   `agentsNotify()` holds the losing write instead of rejecting it, which
+ *   defeats the reconcile loop — there, use `'claim'` or `'queue'`, or change the
+ *   policy.
+ *
+ * - `'claim'` gives mutual exclusion. It takes a fail-fast claim; if another
+ *   participant holds the row, it returns `{ status: 'claimed' }` and leaves the
+ *   decision to retry up to the model. A visible signal serves the agent better
+ *   than a hidden wait when it might spend its turn on something else. Works under
+ *   any conflict policy.
+ *
+ * - `'queue'` serializes writers over stateless HTTP. The tool polls to acquire
+ *   the claim until it is granted or `poll.timeoutMs` elapses, so the model calls
+ *   once and the tool waits its turn. Ordering is approximate rather than strict
+ *   first-in-first-out, which would require a persistent connection.
+ */
+import type { z } from 'zod';
+import type { ModelOperations } from '../client/createModelProxy.js';
+export type CoordinationStrategy = 'merge' | 'claim' | 'queue';
+/** The structured result the tool hands back to the model (or the caller). */
+export interface CoordinatedWriteResult<T> {
+    /**
+     * `'written'` means the change was saved. `'claimed'` means another participant
+     * holds the row, so nothing was saved and the model should try again.
+     * `'timeout'` means the `'queue'` strategy could not acquire the row within
+     * `poll.timeoutMs`.
+     */
+    status: 'written' | 'claimed' | 'timeout';
+    /** The reconciled row, on `'written'`. */
+    row?: T;
+    message?: string;
+    /** On `'written'` via the `queue` strategy, how long the tool waited in line. */
+    waitedMs?: number;
+}
+export interface CoordinatedToolOptions<TInput, T> {
+    /** Tool description shown to the model. */
+    description: string;
+    /** The schema of what the model may send, as a standard AI SDK / Zod input schema. */
+    inputSchema: z.ZodType<TInput>;
+    /** Which row this write targets, derived from the tool input. */
+    id: (input: TInput) => string;
+    /**
+     * Produces the write patch from the freshest current row and the tool input, as
+     * a pure function of the two. Under `'merge'` it re-runs on top of every
+     * concurrent write, so it must be idempotent with respect to its own
+     * contribution — for example, skip its change when its marker is already
+     * present — to stay correct across retries.
+     */
+    apply: (current: T, input: TInput) => Partial<T>;
+    /** How concurrent writers relate. Defaults to `'merge'`. */
+    strategy?: CoordinationStrategy;
+    /** Human-readable coordination metadata attached to the claim, used by the `'claim'` and `'queue'` strategies. */
+    claim?: {
+        reason?: string;
+        description?: string;
+    };
+    /** How many reconcile rounds `'merge'` may take before it gives up with `AbloContentionError`. */
+    retries?: number;
+    /** Poll interval and overall timeout for `'queue'`. Defaults to 250ms and 30s. */
+    poll?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    };
+}
+export declare function coordinatedTool<TInput, T = Record<string, unknown>, CreateInput = Partial<T>>(model: ModelOperations<T, CreateInput>, options: CoordinatedToolOptions<TInput, T>): import("ai").Tool<TInput, CoordinatedWriteResult<T>>;

package/dist/ai-sdk/{coordinated-tool.js → coordinatedTool.js}

@@ -1,15 +1,14 @@
 /**
- * `coordinatedTool` — the one-liner that turns an Ablo model write into a Vercel
- * AI SDK tool with multi-agent coordination already handled, so an AI agent can
- * contribute to shared state without ever silently clobbering a concurrent
- * writer.
+ * Turns a write to one of your models into a Vercel AI SDK tool that handles
+ * multi-agent coordination for you, so an agent can contribute to shared state
+ * without silently overwriting another writer's concurrent change.
  *
- * The base `./ai-sdk` pattern (see index.ts) is "write your own `tool()` and
- * call `ablo.<model>.update({ id, data, claim })` inside `execute`". That's the
- * right amount of control when a tool does something bespoke. But the *common*
- * case — "the agent produced some content; save it into the shared row" — should
- * not require every integration to re-derive optimistic concurrency by hand. This
- * collapses it to a declaration:
+ * The lower-level approach is to write your own `tool()` and call
+ * `ablo.<model>.update({ id, data, claim })` inside its `execute` — the right
+ * amount of control for a bespoke tool. This helper covers the common case
+ * instead: the agent produced some content and you want to save it into a shared
+ * row, without re-deriving optimistic concurrency each time. You declare the
+ * write:
  *
  * ```ts
  * import { coordinatedTool } from '@abloatai/ablo/ai-sdk';
@@ -26,31 +25,37 @@
  * await streamText({ model, messages, tools: { saveSection } });
  * ```
  *
- * `apply` is the whole API: a pure function of `(freshest row, tool input) →
- * patch`, exactly like React's `setState(prev => next)`. Everything underneath —
- * reading the latest row, the compare-and-swap, the jittered backoff between
- * reconcile rounds, releasing claims — is the runtime's job, not yours.
+ * The {@link CoordinatedToolOptions.apply} function is the whole API: a pure
+ * function from the freshest row and the tool input to a patch, in the same
+ * spirit as a functional state update. Everything beneath it — reading the latest
+ * row, the compare-and-swap, backing off between retries, and releasing claims —
+ * is the runtime's job.
  *
- * ## Strategies (pick by how writers should relate; all verified to converge
- * under N-way agent contention)
+ * ## Strategies
  *
- * - `'merge'` *(default)* — delegates straight to the functional update
- *   `ablo.<model>.update(id, current => apply(current, input))`. The SDK re-reads
- *   and re-applies `apply` on top of every concurrent write and backs off between
- *   rounds, so N agents *accumulate* into one row and the model never sees a
- *   conflict. **Requires the model's agent conflict policy to be `reject`** (the
- *   default, or `agentsReject()`); a model declaring `agentsNotify()` HOLDS the
- *   losing write instead of rejecting it, which defeats the reconcile — use
- *   `claim`/`queue` there, or switch the policy.
+ * Choose a strategy by how you want concurrent writers to relate. Each is
+ * designed to converge under many agents writing at once.
  *
- * - `'claim'` — mutual exclusion. Takes a fail-fast claim; if another participant
- *   holds the row it returns `{ status: 'claimed' }` so the *model* decides to
- *   retry (a legible signal beats a hidden wait when the agent might do something
- *   better with its turn). Works regardless of conflict policy.
+ * - `'merge'` (the default) delegates to the functional update
+ *   `ablo.<model>.update(id, current => apply(current, input))`. The runtime
+ *   re-reads and re-applies `apply` on top of every concurrent write, backing off
+ *   between rounds, so many agents accumulate into one row and the model never
+ *   sees a conflict. This requires the model's agent conflict policy to be
+ *   `reject` (the default, or `agentsReject()`). A model that declares
+ *   `agentsNotify()` holds the losing write instead of rejecting it, which
+ *   defeats the reconcile loop — there, use `'claim'` or `'queue'`, or change the
+ *   policy.
  *
- * - `'queue'` — fair-ish serialization over stateless HTTP, the SQS shape: a
- *   client poll-acquire loop (true FIFO needs a socket) until the claim is granted
- *   or `poll.timeoutMs` elapses. The model calls once and the tool waits its turn.
+ * - `'claim'` gives mutual exclusion. It takes a fail-fast claim; if another
+ *   participant holds the row, it returns `{ status: 'claimed' }` and leaves the
+ *   decision to retry up to the model. A visible signal serves the agent better
+ *   than a hidden wait when it might spend its turn on something else. Works under
+ *   any conflict policy.
+ *
+ * - `'queue'` serializes writers over stateless HTTP. The tool polls to acquire
+ *   the claim until it is granted or `poll.timeoutMs` elapses, so the model calls
+ *   once and the tool waits its turn. Ordering is approximate rather than strict
+ *   first-in-first-out, which would require a persistent connection.
  */
 import { tool } from 'ai';
 import { AbloClaimedError, AbloNotFoundError } from '../errors.js';
@@ -63,17 +68,18 @@ export function coordinatedTool(model, options) {
         execute: async (input) => {
             const id = options.id(input);
             if (strategy === 'merge') {
-                // The setState of the data layer: read fresh → apply → CAS → re-read +
-                // re-apply with backoff on any concurrent write. Self-healing; the model
-                // never sees a conflict. (Backoff lives in the shared reconcile loop.)
+                // Read the freshest row, apply the patch, and commit it with a
+                // compare-and-swap; on any concurrent write, re-read and re-apply with
+                // backoff. The model never sees a conflict.
                 const row = await model.update(id, (current) => options.apply(current, input), {
                     retries: options.retries,
                 });
                 return { status: 'written', row: row ?? undefined };
             }
-            // claim / queue both take a claim, write under it, and release. The only
-            // difference is what they do when the row is already held: claim returns the
-            // signal to the model; queue waits and retries (SQS-style poll-acquire).
+            // The 'claim' and 'queue' strategies both acquire a claim, write under it,
+            // and release it. They differ only in what they do when the row is already
+            // held: 'claim' returns a signal to the model, while 'queue' waits and
+            // retries by polling to acquire.
             const acquireWriteRelease = async () => {
                 const claim = await model.claim({
                     id,
@@ -104,7 +110,7 @@ export function coordinatedTool(model, options) {
                     throw e;
                 }
             }
-            // strategy === 'queue': SQS-style poll-acquire over stateless HTTP.
+            // strategy === 'queue': poll to acquire the claim over stateless HTTP.
             const interval = options.poll?.intervalMs ?? 250;
             const timeout = options.poll?.timeoutMs ?? 30_000;
             const start = Date.now();

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

@@ -0,0 +1,46 @@
+/**
+ * Language-model middleware that tells the model when other participants are
+ * editing the same entity. It reads peer claims on the target from the agent's
+ * live presence stream and, when it finds any, injects a short coordination note
+ * into the prompt before the model runs.
+ *
+ * This is the counterpart to the claim-broadcast middleware: that one announces
+ * what this agent is about to do, while this one reads what others are doing and
+ * passes it to the model. Together they let the model notice when a person or
+ * another agent is mid-edit and respond — deferring, framing its work as
+ * complementary, or suggesting it wait.
+ *
+ * It depends only on the AI SDK's provider types and a connected agent from this
+ * package, and you compose it with the AI SDK's `wrapLanguageModel`. Reading
+ * peers costs no extra model calls: the presence stream is already in memory from
+ * the agent's subscription. It adds only a few sentences to the system prompt,
+ * and only while peers are actively editing.
+ */
+import type { LanguageModelV3Middleware } from '@ai-sdk/provider';
+import type { Ablo } from '../client/Ablo.js';
+import type { SchemaRecord } from '../schema/schema.js';
+import type { ClaimTarget } from '../types/streams.js';
+export type { ClaimTarget };
+export interface CoordinationContextMiddlewareOptions<R extends SchemaRecord = SchemaRecord> {
+    readonly agent: Ablo<R> | null;
+    readonly target: ClaimTarget | null;
+    /**
+     * Claim identifiers to leave out of the read, typically this agent's own active
+     * claim so the note doesn't report that the agent is editing against itself. In
+     * the usual composition with the claim-broadcast middleware, `transformParams`
+     * runs before that middleware declares its claim, so the agent's own claim
+     * isn't in the presence stream yet and no filtering is needed. This option is
+     * here for callers that compose the middleware differently, or that coordinate a
+     * fleet and want to exclude sibling workers' claims.
+     */
+    readonly excludeClaimIds?: readonly string[];
+}
+/**
+ * Builds the coordination-context middleware. If `agent` or `target` is null, the
+ * middleware passes the prompt through unchanged.
+ *
+ * The generic over the schema record matches the claim-broadcast middleware: a
+ * typed `Ablo<S>` and the widened `Ablo<SchemaRecord>` are not structurally
+ * assignable, so the parameter stays generic to spare callers a cast.
+ */
+export declare function coordinationContextMiddleware<R extends SchemaRecord = SchemaRecord>(options: CoordinationContextMiddlewareOptions<R>): LanguageModelV3Middleware;

package/dist/ai-sdk/{coordination-context.js → coordinationContext.js}

@@ -1,32 +1,28 @@
 /**
- * Coordination context middleware — reads peer claims on the same
- * entity from the sync engine's presence stream and injects a brief
- * coordination note into the prompt before the LLM call.
+ * Language-model middleware that tells the model when other participants are
+ * editing the same entity. It reads peer claims on the target from the agent's
+ * live presence stream and, when it finds any, injects a short coordination note
+ * into the prompt before the model runs.
  *
- * The complement of `claim-broadcast.ts`: that one declares what
- * THIS agent is about to do; this one reads what OTHERS are doing
- * and tells the LLM about it. Together they make multiplayer-with-
- * AI structurally real — the AI knows when a human or another
- * agent is mid-edit and can defer / phrase its work as
- * "while you finish that, I'll …" / suggest waiting / coordinate
- * explicitly.
+ * This is the counterpart to the claim-broadcast middleware: that one announces
+ * what this agent is about to do, while this one reads what others are doing and
+ * passes it to the model. Together they let the model notice when a person or
+ * another agent is mid-edit and respond — deferring, framing its work as
+ * complementary, or suggesting it wait.
  *
- * Open-source-clean: depends only on `@ai-sdk/provider` types and
- * the package's own `SyncAgent`. Consumers compose via the AI
- * SDK's `wrapLanguageModel`.
- *
- * Cost: zero extra LLM calls (read happens locally from the agent's
- * cached presence stream — already in memory from the WS subscription).
- * Adds a few sentences to the system prompt (typically <100 tokens)
- * only when peers are actively editing.
+ * It depends only on the AI SDK's provider types and a connected agent from this
+ * package, and you compose it with the AI SDK's `wrapLanguageModel`. Reading
+ * peers costs no extra model calls: the presence stream is already in memory from
+ * the agent's subscription. It adds only a few sentences to the system prompt,
+ * and only while peers are actively editing.
  */
 /**
- * Build the middleware. When `agent` or `target` is null, returns a
- * pass-through.
+ * Builds the coordination-context middleware. If `agent` or `target` is null, the
+ * middleware passes the prompt through unchanged.
  *
- * Generic over the schema record — see `claimBroadcastMiddleware`
- * for why `Ablo<S>` and `Ablo<SchemaRecord>` aren't structurally
- * assignable.
+ * The generic over the schema record matches the claim-broadcast middleware: a
+ * typed `Ablo<S>` and the widened `Ablo<SchemaRecord>` are not structurally
+ * assignable, so the parameter stays generic to spare callers a cast.
  */
 export function coordinationContextMiddleware(options) {
     const { agent, target } = options;
@@ -36,13 +32,10 @@ export function coordinationContextMiddleware(options) {
         transformParams: async ({ params }) => {
             if (!agent || !target)
                 return params;
-            // Read peer claims on the same target. Synchronous lookup
-            // against the engine's reactive claims.others array — no I/O.
-            // Type compares case-insensitively: observed claims carry the WIRE
-            // dialect (lowercased typename, `slidedeck`), while callers naturally
-            // write the schema typename (`SlideDeck`) — the same normalization the
-            // commit plane applies (`modelMap` lookups lowercase, and
-            // `targetsOverlap` below already lowercases field/path).
+            // Look up peer claims on the same target. This reads the agent's reactive
+            // `claims.others` array in memory, with no I/O. The type is compared
+            // case-insensitively: observed claims carry a lowercased type name (such as
+            // `slidedeck`) while callers write the schema's type name (`SlideDeck`).
             const wantedType = target.type.toLowerCase();
             const peerClaims = agent.claims.others.filter((claim) => claim.target.type.toLowerCase() === wantedType &&
                 claim.target.id === target.id &&
@@ -78,9 +71,9 @@ function targetsOverlap(claimTarget, target) {
     return fieldOverlaps && rangeOverlaps;
 }
 /**
- * Format a one-paragraph coordination note for the LLM. Includes
- * who's editing and what (when known). Kept short — the goal is
- * "AI knows," not "AI gets a wall of text."
+ * Formats a one-paragraph coordination note for the model. It names who is
+ * editing and, when known, what they are doing. The note stays short: the goal is
+ * to make the model aware, not to flood the prompt.
  */
 function formatCoordinationNote(claims, target) {
     const entityLabel = target.type.toLowerCase();

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

@@ -72,22 +72,24 @@
  * to one entity before any tool is chosen; tool implementations stay exactly
  * the same.
  *
- * ## Multi-agent coordination — the canonical way
- *
- * When several agents (or agents + humans) write the SAME row concurrently, the
- * outcome is decided by **(write path) × (the model's conflict policy)**, NOT by
- * how smart the model is. The same model silently loses 3 of 4 concurrent
- * contributions through a blind whole-row write, and lands all 4 through a
- * coordinated one — because the coordinated write returns a *signal* the model
- * (or the runtime) acts on. Two empirical laws fall out:
- *
- *   1. **Surface the signal.** A write that swallows the conflict and reports
- *      success is the footgun. Every robust path returns a legible result
- *      (`reject` → re-read & retry; `claimed` → the model tries again) instead of
- *      clobbering. Reaching for a bigger model does not fix a silent write.
- *   2. **Back off.** Under N-way contention, writers that retry in lock-step just
- *      re-collide. The shared reconcile loop already jitters its backoff; any
- *      hand-rolled retry must too, or it exhausts its budget and drops a writer.
+ * ## 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":
@@ -107,12 +109,13 @@
  * |----------|-------------------|---------------|------------------------|
  * | `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 (SQS)    | poll-acquire until granted / timeout | any |
+ * | `queue`  | FIFO-ish (poll)   | poll-acquire until granted / timeout | any |
  *
- * Note: a model declaring `agentsNotify()` HOLDS a losing write instead of
- * rejecting it, which defeats `merge`'s reconcile (the loser is dropped, not
- * retried). Use `agentsReject()` for accumulate semantics, or `claim`/`queue`.
+ * 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 './coordination-context.js';
+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 './coordinated-tool.js';
+export { coordinatedTool, type CoordinationStrategy, type CoordinatedToolOptions, type CoordinatedWriteResult, } from './coordinatedTool.js';

package/dist/ai-sdk/index.js

@@ -72,22 +72,24 @@
  * to one entity before any tool is chosen; tool implementations stay exactly
  * the same.
  *
- * ## Multi-agent coordination — the canonical way
- *
- * When several agents (or agents + humans) write the SAME row concurrently, the
- * outcome is decided by **(write path) × (the model's conflict policy)**, NOT by
- * how smart the model is. The same model silently loses 3 of 4 concurrent
- * contributions through a blind whole-row write, and lands all 4 through a
- * coordinated one — because the coordinated write returns a *signal* the model
- * (or the runtime) acts on. Two empirical laws fall out:
- *
- *   1. **Surface the signal.** A write that swallows the conflict and reports
- *      success is the footgun. Every robust path returns a legible result
- *      (`reject` → re-read & retry; `claimed` → the model tries again) instead of
- *      clobbering. Reaching for a bigger model does not fix a silent write.
- *   2. **Back off.** Under N-way contention, writers that retry in lock-step just
- *      re-collide. The shared reconcile loop already jitters its backoff; any
- *      hand-rolled retry must too, or it exhausts its budget and drops a writer.
+ * ## 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":
@@ -107,12 +109,13 @@
  * |----------|-------------------|---------------|------------------------|
  * | `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 (SQS)    | poll-acquire until granted / timeout | any |
+ * | `queue`  | FIFO-ish (poll)   | poll-acquire until granted / timeout | any |
  *
- * Note: a model declaring `agentsNotify()` HOLDS a losing write instead of
- * rejecting it, which defeats `merge`'s reconcile (the loser is dropped, not
- * retried). Use `agentsReject()` for accumulate semantics, or `claim`/`queue`.
+ * 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 './coordination-context.js';
+export { coordinationContextMiddleware, } from './coordinationContext.js';
 export { wrapWithMultiplayer } from './wrap.js';
-export { coordinatedTool, } from './coordinated-tool.js';
+export { coordinatedTool, } from './coordinatedTool.js';

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

@@ -29,7 +29,7 @@ import { wrapLanguageModel } from 'ai';
 import type { LanguageModelV3, LanguageModelV3Middleware } from '@ai-sdk/provider';
 import type { Ablo } from '../client/Ablo.js';
 import type { SchemaRecord } from '../schema/schema.js';
-import { type ClaimTarget } from './coordination-context.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;
@@ -52,14 +52,13 @@ export interface WrapWithMultiplayerOptions<R extends SchemaRecord = SchemaRecor
      */
     readonly excludeClaimIds?: readonly string[];
     /**
-     * Optional extra middleware to compose. Runs in the order given,
-     * INSIDE the multiplayer middlewares (so the multiplayer wrap is
-     * the outer-most). Useful for caching, observability, custom
-     * transforms that should not affect the multiplayer signal.
+     * 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 middleware in the order
-     * you want.
+     * `wrapLanguageModel` directly with all the middleware in the order you want.
      */
     readonly extraMiddleware?: readonly LanguageModelV3Middleware[];
 }