@abloatai/ablo 0.25.0 → 0.27.0

package/dist/agent/session.js

@@ -1,37 +1,35 @@
 /**
- * Agent session — cache + lifecycle for server-side `SyncAgent`s.
+ * Caches and manages the lifecycle of long-lived agent connections on a server.
  *
- * Captures the pattern every server-side consumer needs:
- *   1. Cache `SyncAgent` instances per (org, user, surface, target).
- *   2. Re-mint capabilities before TTL elapses.
- *   3. Align the SyncAgent ctor's `syncGroups` with the cap allowlist
- *      so the upgrade-time intersection is non-empty (avoid the
- *      silent black-hole-broadcast bug).
- *   4. Connect / disconnect / dispose lifecycle.
+ * Server code that runs AI agents typically needs the same four things, and this
+ * module handles all of them:
+ *   1. Reuse one connected agent per (organization, user, surface, target)
+ *      instead of connecting anew on every request.
+ *   2. Re-issue the agent's capability token before it expires.
+ *   3. Request exactly the sync groups the token allows, so the two lists
+ *      overlap. If they don't, the agent subscribes to nothing and every
+ *      broadcast is silently filtered out.
+ *   4. Connect, disconnect, and dispose cleanly.
  *
- * What's generic, what isn't:
- *   - Cache, TTL, sync_groups alignment, lifecycle: SAME for every
- *     consumer. Lives here.
- *   - Cap mint: AUTH-FLOW-SPECIFIC. Every consumer has a different
- *     way to obtain a token (Better Auth cookie forwarding, API key
- *     exchange, OAuth, etc.). Consumer provides via the
- *     `issueToken` callback.
- *
- * The helper itself imports nothing app-specific. Open-source-clean.
+ * Everything except obtaining the token is the same for every caller and lives
+ * here. Obtaining the token depends on how you authenticate — cookie forwarding,
+ * API-key exchange, OAuth, and so on — so you supply that step through the
+ * {@link AgentSessionOptions.issueToken} callback. The module itself depends on
+ * nothing outside this package.
  */
 import { Ablo } from '../client/Ablo.js';
 import { AbloConnectionError } from '../errors.js';
 import { getContext } from '../context.js';
 /**
- * Returns a session whose `getAgent` method handles cache, mint,
- * sync_groups alignment, and lifecycle. Call `disposeAll()` from
- * the consumer's process shutdown hook.
+ * Creates a session that hands out connected agents on demand. Its `getAgent`
+ * method handles caching, token issuance, sync-group alignment, and connection
+ * lifecycle; call `disposeAll` from your process's shutdown hook to close every
+ * open connection.
  *
- * Threading: the session is intended to be a long-lived singleton
- * shared across requests. The cache is keyed precisely so two
- * concurrent requests for the same (user, org, surface, target)
- * share one agent + one WS, while different requests get
- * independent agents.
+ * Treat the session as a long-lived singleton shared across requests. The cache
+ * key combines organization, user, surface, and target, so two concurrent
+ * requests for the same combination share one agent and one WebSocket, while
+ * requests for different combinations get independent agents.
  */
 export function createAgentSession(options) {
     const reissueBufferMs = options.reissueBufferMs ?? 30_000;
@@ -61,21 +59,14 @@ export function createAgentSession(options) {
             }
         }
         const minted = await options.issueToken(identity);
-        // Sync_groups alignment is the load-bearing detail. The SDK
-        // ctor's `syncGroups` and the cap mint's `syncGroups`
-        // MUST overlap or the upgrade intersection is empty and every
-        // broadcast filter returns false. Use the cap's allowed list
-        // verbatim — the caller controlled what went in there, so it's
-        // exactly what the SDK should request.
-        // `AbloOptions` exposes the URL as `baseURL` (resolved by
-        // `resolveBaseURL`). Earlier code passed `url:` here — `Ablo()`
-        // silently dropped the unknown field (the cast below masked the
-        // type error) and `resolveBaseURL` fell through to the hosted
-        // default `wss://api.abloatai.com`. Staging surfaced the bug
-        // 2026-05-07 — DNS lookup hit the wrong
-        // host even though the caller threaded `syncServerUrl` through
-        // correctly. Forward as `baseURL` so the caller's URL is the only
-        // source of truth and the package default never silently applies.
+        // Request the same sync groups the token grants. The groups requested here
+        // and the groups the token allows must overlap; otherwise their intersection
+        // is empty and every broadcast is filtered out. The token's allowed list is
+        // exactly what to request, since the caller decided what went into it.
+        //
+        // Pass the URL as `baseURL`, the field the client reads. Any other field name
+        // is ignored, in which case the client would fall back to its default host,
+        // so `baseURL` keeps the caller's URL the single source of truth.
         const wsUrl = toWsUrl(options.syncServerUrl);
         const agentOptions = {
             baseURL: wsUrl,
@@ -101,11 +92,9 @@ export function createAgentSession(options) {
                 await agent.dispose();
             }
             catch { /* ignore */ }
-            // Route through the gated logger so this obeys ABLO_LOG_LEVEL like every
-            // other line: a plain consumer-register `error` headline (the unreachable
-            // URL + code), with the structured fields on a `debug` companion. The
-            // companion's shape matches the cap-mint logger in `connectAgent.ts` so a
-            // single search picks both up.
+            // Log through the level-gated logger so it honors ABLO_LOG_LEVEL: an
+            // `error` headline naming the unreachable URL and code, plus a `debug`
+            // companion carrying the structured fields for deeper diagnosis.
             const log = getContext().logger;
             log.error(`Agent could not connect to the sync server at ${wsUrl}${code ? ` (${code})` : ''}.`);
             log.debug('[Agent.session] ws bootstrap failed', {
@@ -135,9 +124,9 @@ export function createAgentSession(options) {
         cacheByKey.clear();
     }
     /**
-     * Eject a specific cached agent — useful when the consumer knows
-     * the underlying token is invalidated (revocation, role change)
-     * and wants the next `getAgent` call to mint fresh.
+     * Removes and disposes one cached agent. Call it when you know the agent's
+     * token is no longer valid — after a revocation or role change, for example —
+     * so the next `getAgent` call issues a fresh one.
      */
     function evict(identity) {
         const key = cacheKey(identity);

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,9 +32,12 @@ 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.
-            const peerClaims = agent.claims.others.filter((claim) => claim.target.type === target.type &&
+            // 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 &&
                 targetsOverlap(claim.target, target) &&
                 !excludeClaimIds.has(claim.id));
@@ -72,14 +71,14 @@ 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();
-    if (claims.length === 1) {
-        const c = claims[0];
+    const c = claims.length === 1 ? claims[0] : undefined;
+    if (c) {
         const details = c.description ? `Declared work: ${c.description}. ` : '';
         return (`<multiplayer_context>\n` +
             `Another participant is currently editing this ${entityLabel}. ` +