@abloatai/ablo 0.3.0

package/dist/agent/index.js

@@ -0,0 +1,128 @@
+/**
+ * @ablo/sync-engine-internal/agent — Agent SDK helpers
+ *
+ * Two entry points depending on agent lifetime:
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * LONG-LIVED AGENT (browser, daemon, persistent Node process)
+ * ─────────────────────────────────────────────────────────────────────────
+ * Use the unified `Ablo({...})` factory directly with `kind: 'agent'`.
+ * The factory holds the WebSocket, reactive subscriptions, mutations, and
+ * presence/intents — same surface as a browser user, just with a
+ * server-issued capability token instead of session cookies.
+ *
+ * ```ts
+ * import Ablo from '@ablo/sync-engine';
+ *
+ * const ablo = Ablo({
+ *   schema,
+ *   url: 'wss://api.example.com',
+ *   organizationId,
+ *   kind: 'agent',
+ *   agentId: 'reviewer-bot',
+ *   capabilityToken: mintedToken,
+ *   syncGroups: [`org:${organizationId}`],
+ *   inMemory: true,  // Node has no IndexedDB
+ * });
+ *
+ * await ablo.ready();
+ * for (const task of ablo.tasks.list({ where: { status: 'pending_review' } })) {
+ *   await ablo.tasks.update(task.id, { status: 'reviewed' });
+ * }
+ * ```
+ *
+ * For server-side caching across requests, use {@link Agent.session}
+ * — it caches one engine per identity and refreshes capability tokens
+ * before expiry.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * SHORT-LIVED AGENT (SQS consumer, serverless, API route)
+ * ─────────────────────────────────────────────────────────────────────────
+ * Use {@link Agent}. Stateless REST hooks that slot directly into
+ * the Vercel AI SDK's `generateText` / `streamText`. No WebSocket. Ideal
+ * for agent-worker jobs that process one task and exit.
+ *
+ * ```ts
+ * import { generateText, tool, stepCountIs } from 'ai';
+ * import { Agent } from '@ablo/sync-engine-internal/agent';
+ *
+ * const perception = new Agent({
+ *   syncServerUrl: 'http://localhost:8080',
+ *   agentId: job.id,
+ *   organizationId: job.organizationId,
+ *   syncGroups: [`org:${job.organizationId}`],
+ * });
+ *
+ * await generateText({
+ *   model: 'anthropic/claude-sonnet-4.5',
+ *   messages,
+ *   stopWhen: stepCountIs(10),
+ *   tools: {
+ *     updateSlide: perception.wrapTool(tool({ ... }), {
+ *       entityType: 'Slide',
+ *       getEntityId: (args) => args.id,
+ *     }),
+ *   },
+ *   prepareStep: perception.prepareStep(),
+ *   onStepFinish: perception.onStepFinish(),
+ * });
+ * ```
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * IDIOMATIC TOOL PATTERN (ported from vercel-labs/open-agents)
+ * ─────────────────────────────────────────────────────────────────────────
+ * Tools are factory functions that pull ambient state from
+ * `experimental_context`. The caller builds an {@link AgentContext} once
+ * and passes it to `generateText`; every tool reaches in.
+ *
+ * ```ts
+ * import { tool } from 'ai';
+ * import { z } from 'zod';
+ * import { Agent, type AgentContext } from '@ablo/sync-engine-internal/agent';
+ *
+ * export const updateSlideTool = () => tool({
+ *   description: 'Update a slide title',
+ *   inputSchema: z.object({ id: z.string(), title: z.string() }),
+ *   execute: async (args, { experimental_context }) => {
+ *     const perception = Agent.fromContext(experimental_context, 'updateSlide');
+ *     const check = await perception.checkFreshness('Slide', args.id, Date.now() - 5000);
+ *     if (check.stale) return check.summary;
+ *     return { ok: true };
+ *   },
+ * });
+ * ```
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * COMPOSED (long-lived `Ablo({kind:'agent'})` + Agent together)
+ * ─────────────────────────────────────────────────────────────────────────
+ * If you have a long-lived `Ablo` instance AND want AI SDK hooks, pass it
+ * as the `announcer` to Agent — presence announcements route
+ * through the existing WebSocket instead of opening new HTTP calls.
+ *
+ * ```ts
+ * const ablo = Ablo({ kind: 'agent', schema, capabilityToken, ... });
+ * await ablo.ready();
+ *
+ * const perception = new Agent({
+ *   ...sharedConfig,
+ *   announcer: ablo,  // reuse the WebSocket
+ * });
+ * ```
+ *
+ * Both `Ablo` and `Agent` implement the
+ * {@link PresenceAnnouncer} interface.
+ */
+// ── The entire `/agent` surface — one symbol ────────────────────────────
+//
+// `Agent` is the class AND the namespace for its types. Reach for
+// options, context, and session options via dot access:
+//
+//   import { Agent } from '@ablo/sync-engine-internal/agent';
+//   const opts: Agent.Options = { ... };
+//   const ctx:  Agent.Context = { perception };
+//   const s:    Agent.SessionOptions = { ... };
+//
+// Everything else (Activity, Claim, Turn, Peer, ActiveIntent, ...)
+// lives on the `Ablo.*` namespace via
+// `import type { Ablo } from '@ablo/sync-engine'`.
+export { Agent } from './Agent.js';

package/dist/agent/session.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Agent session — cache + lifecycle for server-side `SyncAgent`s.
+ *
+ * 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.
+ *
+ * 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.
+ */
+import { Ablo } from '../client/Ablo.js';
+import type { Schema, SchemaRecord } from '../schema/schema.js';
+interface IssuedToken {
+    readonly token: string;
+    readonly expiresAtMs: number;
+    /**
+     * Sync groups allowed by this capability. Must include every group
+     * the agent will subscribe to — the upgrade-time intersection of
+     * (allowed) ∩ (requested) determines effective subscription. Returning
+     * a list that doesn't include the needed groups produces an empty
+     * intersection and silent broadcast failure.
+     */
+    readonly syncGroups: readonly string[];
+}
+interface AgentIdentity {
+    readonly userId: string;
+    readonly organizationId: string;
+    /**
+     * Surface class — `'chat'`, `'mcp'`, `'agent_worker'`, etc. Session
+     * caches per surface so two surfaces don't share token or WS.
+     */
+    readonly surfaceClass: string;
+    readonly target?: {
+        readonly entityType: string;
+        readonly entityId: string;
+    } | null;
+}
+export interface AgentSessionOptions<R extends SchemaRecord = SchemaRecord> {
+    /** Sync-server WebSocket URL — `wss://sync.example.com` or `ws://localhost:3001`. */
+    readonly syncServerUrl: string;
+    /** Schema for the typed model proxy on the returned Ablo. After
+     *  the dual-engine collapse, `Ablo({kind:'agent'})` is the unified
+     *  factory and requires the schema to expose
+     *  `agent.<model>.create/update/delete`. */
+    readonly schema: Schema<R>;
+    /**
+     * Token-issuing callback. Called on cache miss / expiry. Owns the
+     * consumer's auth flow (Better Auth cookies, API key exchange, OAuth,
+     * etc.) so the engine stays auth-flow-agnostic.
+     */
+    readonly issueToken: (identity: AgentIdentity) => Promise<IssuedToken>;
+    /**
+     * Soft window before actual expiry to re-mint. Defaults to 30s.
+     * Avoids races between mint-time and clock-skew at use-time.
+     */
+    readonly reissueBufferMs?: number;
+    /**
+     * Optional agent-id strategy. Default: `${surfaceClass}:${userId}`.
+     * Override when the consumer wants different attribution shape.
+     */
+    readonly agentIdFor?: (identity: AgentIdentity) => string;
+}
+/**
+ * Returns a session whose `getAgent` method handles cache, mint,
+ * sync_groups alignment, and lifecycle. Call `disposeAll()` from
+ * the consumer's process shutdown hook.
+ *
+ * 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.
+ */
+export declare function createAgentSession<R extends SchemaRecord = SchemaRecord>(options: AgentSessionOptions<R>): {
+    getAgent: (identity: AgentIdentity) => Promise<Ablo<R>>;
+    evict: (identity: AgentIdentity) => void;
+    disposeAll: () => void;
+};
+export {};

package/dist/agent/session.js

@@ -0,0 +1,156 @@
+/**
+ * Agent session — cache + lifecycle for server-side `SyncAgent`s.
+ *
+ * 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.
+ *
+ * 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.
+ */
+import { Ablo } from '../client/Ablo.js';
+/**
+ * Returns a session whose `getAgent` method handles cache, mint,
+ * sync_groups alignment, and lifecycle. Call `disposeAll()` from
+ * the consumer's process shutdown hook.
+ *
+ * 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.
+ */
+export function createAgentSession(options) {
+    const reissueBufferMs = options.reissueBufferMs ?? 30_000;
+    const agentIdFor = options.agentIdFor ??
+        ((id) => `${id.surfaceClass}:${id.userId}`);
+    const cacheByKey = new Map();
+    function cacheKey(id) {
+        const targetSeg = id.target
+            ? `:${id.target.entityType}:${id.target.entityId}`
+            : '';
+        return `${id.organizationId}:${id.userId}:${id.surfaceClass}${targetSeg}`;
+    }
+    async function getAgent(identity) {
+        const key = cacheKey(identity);
+        const cached = cacheByKey.get(key);
+        if (cached && cached.expiresAtMs - Date.now() > reissueBufferMs) {
+            return cached.agent;
+        }
+        // Best-effort cleanup of stale agent — don't let a stuck cached
+        // entry block fresh issuance.
+        if (cached) {
+            try {
+                await cached.agent.dispose();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        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 hardcoded
+        // default `wss://api.ablo.cloud` (now `wss://mesh.ablo.finance`).
+        // 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.
+        const wsUrl = toWsUrl(options.syncServerUrl);
+        const agentOptions = {
+            baseURL: wsUrl,
+            schema: options.schema,
+            kind: 'agent',
+            capabilityToken: minted.token,
+            agentId: agentIdFor(identity),
+            organizationId: identity.organizationId,
+            syncGroups: [...minted.syncGroups],
+            // Agents run in Node — no IDB available, no need for it.
+            inMemory: true,
+        };
+        const agent = Ablo(agentOptions);
+        try {
+            await agent.ready();
+        }
+        catch (err) {
+            const e = err;
+            const code = e.cause?.code;
+            const causeMsg = e.cause?.message;
+            // Best-effort dispose so the failed agent doesn't leak ws state.
+            try {
+                await agent.dispose();
+            }
+            catch { /* ignore */ }
+            // Use console.error directly (rather than the engine logger)
+            // because this path may run before the per-agent logger is
+            // attached. The structured fields match the cap-mint logger in
+            // `connectAgent.ts` so a single search picks both up.
+            // eslint-disable-next-line no-console
+            console.error('[Agent.session] ws bootstrap failed', {
+                url: wsUrl,
+                surfaceClass: identity.surfaceClass,
+                orgId: identity.organizationId,
+                userId: identity.userId,
+                code,
+                causeMsg,
+                err,
+            });
+            throw new Error(`ws bootstrap ${wsUrl} failed: ${e.message ?? 'bootstrap failed'}` +
+                (code ? ` (${code})` : ''));
+        }
+        cacheByKey.set(key, { agent, expiresAtMs: minted.expiresAtMs });
+        return agent;
+    }
+    function disposeAll() {
+        for (const { agent } of cacheByKey.values()) {
+            try {
+                void agent.dispose();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        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.
+     */
+    function evict(identity) {
+        const key = cacheKey(identity);
+        const cached = cacheByKey.get(key);
+        if (cached) {
+            try {
+                void cached.agent.dispose();
+            }
+            catch {
+                /* ignore */
+            }
+            cacheByKey.delete(key);
+        }
+    }
+    return { getAgent, evict, disposeAll };
+}
+/** `https://host` → `wss://host`; `http://host` → `ws://host`. */
+function toWsUrl(url) {
+    return url.replace(/^http/, 'ws');
+}

package/dist/agent/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Agent-SDK abstractions. The engine's data vocabulary
+ * (`Peer`, `Activity`, `IntentClaim`, `ActiveIntent`,
+ * `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).
+ */
+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.
+ */
+export interface PresenceAnnouncer {
+    announce(status: 'online' | 'away' | 'offline', activity?: Activity): Promise<void>;
+}
+/**
+ * Ambient context threaded into AI SDK tools via `experimental_context`.
+ *
+ * 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.
+ *
+ * ```ts
+ * import { generateText, tool } from 'ai';
+ * import { Agent, type AgentContext } from '@ablo/sync-engine-internal/agent';
+ *
+ * const updateSlideTool = () => tool({
+ *   inputSchema: z.object({ id: z.string(), title: z.string() }),
+ *   execute: async (args, { experimental_context }) => {
+ *     const perception = Agent.fromContext(experimental_context);
+ *     const check = await perception.checkFreshness('Slide', args.id, Date.now() - 5000);
+ *     if (check.stale) return check.summary;
+ *     // ... actual mutation
+ *   },
+ * });
+ *
+ * await generateText({
+ *   model: 'anthropic/claude-sonnet-4.5',
+ *   tools: { updateSlide: updateSlideTool() },
+ *   experimental_context: { perception, organizationId, userId } satisfies AgentContext,
+ * });
+ * ```
+ *
+ * Consumers can extend AgentContext via module augmentation or by
+ * intersecting with their own context type.
+ */
+export interface AgentContext {
+    /** Presence / freshness / AI SDK hook primitives. Required. */
+    perception: PresenceAnnouncer & {
+        checkFreshness?: (entityType: string, entityId: string, lastSeenAt: number) => Promise<unknown>;
+    };
+    /** Organization scope for all operations. */
+    organizationId?: string;
+    /** User or agent identifier — format: "agent:<id>" for agents. */
+    userId?: string;
+    /** Sync groups the agent belongs to. */
+    syncGroups?: string[];
+    /** Allow extension with product-specific fields. */
+    [key: string]: unknown;
+}

package/dist/agent/types.js

@@ -0,0 +1,10 @@
+/**
+ * Agent-SDK abstractions. The engine's data vocabulary
+ * (`Peer`, `Activity`, `IntentClaim`, `ActiveIntent`,
+ * `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).
+ */
+export {};

package/dist/ai-sdk/coordination-context.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Coordination context middleware — reads peer intents on the same
+ * entity from the sync engine's presence stream and injects a brief
+ * coordination note into the prompt before the LLM call.
+ *
+ * The complement of `intent-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.
+ *
+ * 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.
+ */
+import type { LanguageModelV3Middleware } from '@ai-sdk/provider';
+import type { Ablo } from '../client/Ablo.js';
+import type { SchemaRecord } from '../schema/schema.js';
+import type { IntentTarget } from './intent-broadcast.js';
+export interface CoordinationContextMiddlewareOptions<R extends SchemaRecord = SchemaRecord> {
+    readonly agent: Ablo<R> | null;
+    readonly target: IntentTarget | null;
+    /**
+     * Optional intentId(s) to exclude from the read — typically this
+     * agent's own active claim so the coordination note doesn't tell
+     * the AI "you yourself are editing this." When middleware is
+     * composed with `intentBroadcastMiddleware` in the standard order,
+     * `transformParams` runs BEFORE the broadcast's `wrapStream`
+     * declares its claim, so the agent's own claim isn't yet in the
+     * cached presence and self-filtering isn't needed. The hook is
+     * here for callers that compose differently or for fleet
+     * coordination (filter sibling worker intents).
+     */
+    readonly excludeIntentIds?: readonly string[];
+}
+/**
+ * Build the middleware. When `agent` or `target` is null, returns a
+ * pass-through.
+ *
+ * Generic over the schema record — see `intentBroadcastMiddleware`
+ * for why `Ablo<S>` and `Ablo<SchemaRecord>` aren't structurally
+ * assignable.
+ */
+export declare function coordinationContextMiddleware<R extends SchemaRecord = SchemaRecord>(options: CoordinationContextMiddlewareOptions<R>): LanguageModelV3Middleware;

package/dist/ai-sdk/coordination-context.js

@@ -0,0 +1,107 @@
+/**
+ * Coordination context middleware — reads peer intents on the same
+ * entity from the sync engine's presence stream and injects a brief
+ * coordination note into the prompt before the LLM call.
+ *
+ * The complement of `intent-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.
+ *
+ * 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.
+ */
+/**
+ * Build the middleware. When `agent` or `target` is null, returns a
+ * pass-through.
+ *
+ * Generic over the schema record — see `intentBroadcastMiddleware`
+ * for why `Ablo<S>` and `Ablo<SchemaRecord>` aren't structurally
+ * assignable.
+ */
+export function coordinationContextMiddleware(options) {
+    const { agent, target } = options;
+    const excludeIntentIds = new Set(options.excludeIntentIds ?? []);
+    return {
+        specificationVersion: 'v3',
+        transformParams: async ({ params }) => {
+            if (!agent || !target)
+                return params;
+            // Read peer intents on the same target. Synchronous lookup
+            // against the engine's reactive intents.others array — no I/O.
+            const peerClaims = agent.intents.others.filter((claim) => claim.target.type === target.entityType &&
+                claim.target.id === target.entityId &&
+                targetsOverlap(claim.target, target) &&
+                !excludeIntentIds.has(claim.id));
+            if (peerClaims.length === 0)
+                return params;
+            const note = formatCoordinationNote(peerClaims, target);
+            return injectSystemNote(params, note);
+        },
+    };
+}
+function hasSubtarget(target) {
+    return Boolean(target.path || target.field || target.range);
+}
+function rangesOverlap(a, b) {
+    return a.startLine <= b.endLine && b.startLine <= a.endLine;
+}
+function targetsOverlap(claimTarget, target) {
+    if (!hasSubtarget(claimTarget) || !hasSubtarget(target))
+        return true;
+    if (claimTarget.path &&
+        target.path &&
+        claimTarget.path.toLowerCase() !== target.path.toLowerCase()) {
+        return false;
+    }
+    const fieldOverlaps = !claimTarget.field ||
+        !target.field ||
+        claimTarget.field.toLowerCase() === target.field.toLowerCase();
+    const rangeOverlaps = !claimTarget.range ||
+        !target.range ||
+        rangesOverlap(claimTarget.range, target.range);
+    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."
+ */
+function formatCoordinationNote(claims, target) {
+    const entityLabel = target.entityType.toLowerCase();
+    if (claims.length === 1) {
+        const c = claims[0];
+        return (`<multiplayer_context>\n` +
+            `Another participant is currently editing this ${entityLabel}. ` +
+            `Action declared: ${c.reason}. ` +
+            `Defer to their concurrent changes when reasonable, or note your work as complementary to theirs. ` +
+            `Avoid stomping their in-flight edits.\n` +
+            `</multiplayer_context>`);
+    }
+    const actions = Array.from(new Set(claims.map((c) => c.reason))).join(', ');
+    return (`<multiplayer_context>\n` +
+        `${claims.length} other participants are currently editing this ${entityLabel}. ` +
+        `Active actions: ${actions}. ` +
+        `Coordinate with their in-flight work — defer where reasonable, ` +
+        `or describe your work as complementary.\n` +
+        `</multiplayer_context>`);
+}
+/**
+ * Append a system-role message to the prompt array. The AI SDK's
+ * `LanguageModelV3Prompt` is an ordered list of messages.
+ */
+function injectSystemNote(params, note) {
+    return {
+        ...params,
+        prompt: [...params.prompt, { role: 'system', content: note }],
+    };
+}