@abloatai/ablo 0.3.0

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

@@ -0,0 +1,68 @@
+/**
+ * `@ablo/sync-engine-internal/ai-sdk` — multiplayer-with-AI as language model
+ * middleware.
+ *
+ * Two cross-cutting middlewares for any AI SDK consumer using
+ * `streamText` / `generateText`:
+ *
+ *   - `intentBroadcastMiddleware` — agent declares what it's about
+ *     to mutate via `intent_begin`, abandons the claim at stream end.
+ *     Peers see the broadcast in their presence stream's
+ *     `activeIntents` field and can defer / yield / surface
+ *     "agent is editing this entity right now."
+ *
+ *   - `coordinationContextMiddleware` — reads peer intents from local
+ *     presence cache before the LLM call, injects a
+ *     `<multiplayer_context>` system note when peers are editing
+ *     the same entity. The AI gets coordination awareness without
+ *     extra round-trips.
+ *
+ * Compose them with the AI SDK's `wrapLanguageModel`:
+ *
+ * ```ts
+ * import { wrapLanguageModel, streamText } from 'ai';
+ * import {
+ *   intentBroadcastMiddleware,
+ *   coordinationContextMiddleware,
+ * } from '@ablo/sync-engine-internal/ai-sdk';
+ *
+ * const target = { entityType: 'SlideDeck', entityId: 'deck-abc' };
+ *
+ * const wrappedModel = wrapLanguageModel({
+ *   model: anthropic('claude-opus-4-7'),
+ *   middleware: [
+ *     coordinationContextMiddleware({ agent, target }),
+ *     intentBroadcastMiddleware({ agent, target }),
+ *   ],
+ * });
+ *
+ * // Consumer keeps full control over messages, tools, system prompt:
+ * const result = streamText({
+ *   model: wrappedModel,
+ *   messages: [...],
+ *   tools: { ... },
+ *   system: '...',
+ * });
+ * ```
+ *
+ * Or use the convenience composition for the common case:
+ *
+ * ```ts
+ * import { wrapWithMultiplayer } from '@ablo/sync-engine-internal/ai-sdk';
+ *
+ * const wrappedModel = wrapWithMultiplayer({
+ *   model: anthropic('claude-opus-4-7'),
+ *   agent,
+ *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
+ * });
+ * ```
+ *
+ * Order matters: `coordinationContextMiddleware`'s `transformParams`
+ * runs at param-transform time (before the model call), reading peer
+ * intents *before* this agent's broadcast lands in its own cache.
+ * `intentBroadcastMiddleware`'s `wrapStream` runs around the actual
+ * call. Self-claim doesn't pollute the peer-intent read.
+ */
+export { intentBroadcastMiddleware, type IntentTarget, type IntentBroadcastMiddlewareOptions, } from './intent-broadcast.js';
+export { coordinationContextMiddleware, type CoordinationContextMiddlewareOptions, } from './coordination-context.js';
+export { wrapWithMultiplayer, type WrapWithMultiplayerOptions } from './wrap.js';

package/dist/ai-sdk/index.js

@@ -0,0 +1,68 @@
+/**
+ * `@ablo/sync-engine-internal/ai-sdk` — multiplayer-with-AI as language model
+ * middleware.
+ *
+ * Two cross-cutting middlewares for any AI SDK consumer using
+ * `streamText` / `generateText`:
+ *
+ *   - `intentBroadcastMiddleware` — agent declares what it's about
+ *     to mutate via `intent_begin`, abandons the claim at stream end.
+ *     Peers see the broadcast in their presence stream's
+ *     `activeIntents` field and can defer / yield / surface
+ *     "agent is editing this entity right now."
+ *
+ *   - `coordinationContextMiddleware` — reads peer intents from local
+ *     presence cache before the LLM call, injects a
+ *     `<multiplayer_context>` system note when peers are editing
+ *     the same entity. The AI gets coordination awareness without
+ *     extra round-trips.
+ *
+ * Compose them with the AI SDK's `wrapLanguageModel`:
+ *
+ * ```ts
+ * import { wrapLanguageModel, streamText } from 'ai';
+ * import {
+ *   intentBroadcastMiddleware,
+ *   coordinationContextMiddleware,
+ * } from '@ablo/sync-engine-internal/ai-sdk';
+ *
+ * const target = { entityType: 'SlideDeck', entityId: 'deck-abc' };
+ *
+ * const wrappedModel = wrapLanguageModel({
+ *   model: anthropic('claude-opus-4-7'),
+ *   middleware: [
+ *     coordinationContextMiddleware({ agent, target }),
+ *     intentBroadcastMiddleware({ agent, target }),
+ *   ],
+ * });
+ *
+ * // Consumer keeps full control over messages, tools, system prompt:
+ * const result = streamText({
+ *   model: wrappedModel,
+ *   messages: [...],
+ *   tools: { ... },
+ *   system: '...',
+ * });
+ * ```
+ *
+ * Or use the convenience composition for the common case:
+ *
+ * ```ts
+ * import { wrapWithMultiplayer } from '@ablo/sync-engine-internal/ai-sdk';
+ *
+ * const wrappedModel = wrapWithMultiplayer({
+ *   model: anthropic('claude-opus-4-7'),
+ *   agent,
+ *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
+ * });
+ * ```
+ *
+ * Order matters: `coordinationContextMiddleware`'s `transformParams`
+ * runs at param-transform time (before the model call), reading peer
+ * intents *before* this agent's broadcast lands in its own cache.
+ * `intentBroadcastMiddleware`'s `wrapStream` runs around the actual
+ * call. Self-claim doesn't pollute the peer-intent read.
+ */
+export { intentBroadcastMiddleware, } from './intent-broadcast.js';
+export { coordinationContextMiddleware, } from './coordination-context.js';
+export { wrapWithMultiplayer } from './wrap.js';

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

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

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

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

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

@@ -0,0 +1,67 @@
+/**
+ * Convenience composition for the common case — wraps a language
+ * model with both multiplayer middlewares (intent broadcast +
+ * coordination context) in the right order.
+ *
+ * Consumers who want full control over middleware composition (add
+ * caching / observability / their own custom middleware) should use
+ * the factories directly: `intentBroadcastMiddleware`,
+ * `coordinationContextMiddleware`. This helper is the one-liner for
+ * the 90% case.
+ *
+ * Stays explicit about its scope — wraps the MODEL only. Consumer
+ * keeps full control over their `streamText` / `generateText` call
+ * (messages, tools, system prompt, provider options, onFinish, etc.).
+ *
+ * ```ts
+ * const wrapped = wrapWithMultiplayer({
+ *   model: anthropic('claude-opus-4-7'),
+ *   agent,
+ *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
+ * });
+ *
+ * const result = streamText({
+ *   model: wrapped,
+ *   messages: myMessages,
+ *   tools: myTools,
+ *   system: mySystem,
+ *   // ... anything else the consumer's app needs
+ * });
+ * ```
+ */
+import { wrapLanguageModel } from 'ai';
+import type { LanguageModelV3, LanguageModelV3Middleware } from '@ai-sdk/provider';
+import type { Ablo } from '../client/Ablo.js';
+import type { SchemaRecord } from '../schema/schema.js';
+import { type IntentTarget } from './intent-broadcast.js';
+export interface WrapWithMultiplayerOptions {
+    /** The base language model to wrap. Consumer brings their own. */
+    readonly model: LanguageModelV3;
+    /** Connected SyncAgent. Null = pass-through wrap (no broadcast, no read). */
+    readonly agent: Ablo<SchemaRecord> | null;
+    /** Target entity. Null = pass-through wrap. */
+    readonly target: IntentTarget | null;
+    /**
+     * Optional action verb for the broadcast. Default `'edit'`.
+     * Convention: `'edit'`, `'read'`, `'review'`, `'generate'`.
+     */
+    readonly action?: string;
+    /**
+     * Optional intentIds to exclude from the coordination-context
+     * read — typically the caller's own claim if they're composing
+     * multiple wrappings. Most consumers leave this empty.
+     */
+    readonly excludeIntentIds?: 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.
+     *
+     * For full control over ordering, skip this helper and call
+     * `wrapLanguageModel` directly with all middleware in the order
+     * you want.
+     */
+    readonly extraMiddleware?: readonly LanguageModelV3Middleware[];
+}
+export declare function wrapWithMultiplayer(options: WrapWithMultiplayerOptions): ReturnType<typeof wrapLanguageModel>;

package/dist/ai-sdk/wrap.js

@@ -0,0 +1,45 @@
+/**
+ * Convenience composition for the common case — wraps a language
+ * model with both multiplayer middlewares (intent broadcast +
+ * coordination context) in the right order.
+ *
+ * Consumers who want full control over middleware composition (add
+ * caching / observability / their own custom middleware) should use
+ * the factories directly: `intentBroadcastMiddleware`,
+ * `coordinationContextMiddleware`. This helper is the one-liner for
+ * the 90% case.
+ *
+ * Stays explicit about its scope — wraps the MODEL only. Consumer
+ * keeps full control over their `streamText` / `generateText` call
+ * (messages, tools, system prompt, provider options, onFinish, etc.).
+ *
+ * ```ts
+ * const wrapped = wrapWithMultiplayer({
+ *   model: anthropic('claude-opus-4-7'),
+ *   agent,
+ *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
+ * });
+ *
+ * const result = streamText({
+ *   model: wrapped,
+ *   messages: myMessages,
+ *   tools: myTools,
+ *   system: mySystem,
+ *   // ... anything else the consumer's app needs
+ * });
+ * ```
+ */
+import { wrapLanguageModel } from 'ai';
+import { intentBroadcastMiddleware, } from './intent-broadcast.js';
+import { coordinationContextMiddleware } from './coordination-context.js';
+export function wrapWithMultiplayer(options) {
+    const { model, agent, target, action, excludeIntentIds, extraMiddleware } = options;
+    return wrapLanguageModel({
+        model,
+        middleware: [
+            coordinationContextMiddleware({ agent, target, excludeIntentIds }),
+            intentBroadcastMiddleware({ agent, target, action }),
+            ...(extraMiddleware ?? []),
+        ],
+    });
+}

package/dist/api/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Internal compatibility entrypoint for the stateless hosted protocol client.
+ *
+ * Use this build for serverless functions, scripts, and backends that want
+ * Resource / Intent / Commit over HTTP without the realtime sync runtime.
+ */
+export { createProtocolClient, createProtocolClient as Ablo, type AbloApi, type AbloApiClientOptions, type AbloApiIntents, type Agent, type AgentIntentInput, type AgentIntentOptions, type AgentOptions, type AgentResourceClient, type AgentResourceReadOptions, type AgentResourceMutationOptions, type AgentRunContext, type AgentRunDone, type AgentRunFailed, type AgentRunCancelled, type AgentRunOptions, type AgentRunResult, type AgentRunStatus, type Capability, type CapabilityCreateOptions, type CapabilityParticipantKind, type CapabilityRecord, type CapabilityResource, type CapabilityRevocation, type CapabilityScope, type Task, type TaskCloseOptions, type TaskCloseResult, type TaskCreateOptions, type TaskResource, } from '../client/ApiClient.js';
+export type { CommitCreateOptions, CommitOperationInput, CommitReceipt, CommitWait, IntentCreateOptions, IntentHandle, IntentWaitOptions, BusyOptions, BusyPolicy, ResourceClient, ResourceIntent, ResourceMutationOptions, ResourceReadOptions, ResourceRead, ResourceTarget, } from '../client/Ablo.js';
+import { createProtocolClient } from '../client/ApiClient.js';
+export default createProtocolClient;

package/dist/api/index.js

@@ -0,0 +1,9 @@
+/**
+ * Internal compatibility entrypoint for the stateless hosted protocol client.
+ *
+ * Use this build for serverless functions, scripts, and backends that want
+ * Resource / Intent / Commit over HTTP without the realtime sync runtime.
+ */
+export { createProtocolClient, createProtocolClient as Ablo, } from '../client/ApiClient.js';
+import { createProtocolClient } from '../client/ApiClient.js';
+export default createProtocolClient;

package/dist/auth/index.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Internal apiKey → capability exchange.
+ *
+ * Called by the `Ablo({...})` factory's `ready()` flow when the
+ * consumer passed `apiKey` without an explicit `capabilityToken` /
+ * `organizationId` / `user.id`. SDK calls `/auth/capability` once,
+ * server returns the scope + userMeta blobs (Phases 1A + 1B),
+ * SDK populates internal state from the response.
+ *
+ * Consumer never sees this happen. Same shape as Stripe / Anthropic
+ * SDKs hide their internal auth-handshake — the apiKey is the only
+ * credential the consumer touches.
+ */
+/** Server response shape — matches Phase 1A + 1B wire output. */
+export interface CapabilityExchangeResponse {
+    readonly capabilityId: string;
+    readonly token: string;
+    readonly expiresAt: string;
+    readonly organizationId: string;
+    readonly scope: {
+        readonly organizationId: string;
+        readonly syncGroups: readonly string[];
+        readonly operations: readonly string[];
+        readonly participantKind: 'user' | 'agent' | 'system';
+        readonly participantId: string;
+    };
+    readonly userMeta: Record<string, unknown>;
+}
+export interface ExchangeApiKeyRequest {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly participantKind: 'user' | 'agent' | 'system';
+    readonly participantId?: string;
+    readonly syncGroups?: readonly string[];
+    readonly operations?: readonly string[];
+    readonly wideScope?: boolean;
+    readonly ttlSeconds: number;
+    readonly label?: string;
+    readonly userMeta?: Record<string, unknown>;
+    readonly fetch?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+export declare function exchangeApiKey(options: ExchangeApiKeyRequest): Promise<CapabilityExchangeResponse>;
+export interface IdentityResolveResponse {
+    readonly participantKind: 'user' | 'agent' | 'system';
+    readonly participantId: string;
+    readonly accountScope: string;
+    readonly syncGroups: readonly string[];
+    readonly userMeta: Record<string, unknown>;
+}
+export interface ResolveIdentityRequest {
+    readonly baseUrl: string;
+    readonly authToken?: string;
+    readonly fetch?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+/**
+ * Resolve the caller's Ablo identity from the authenticated request
+ * context. Used by browser/session/capability flows where the SDK should
+ * not require a public `userId` prop just to open local storage.
+ */
+export declare function resolveIdentity(options: ResolveIdentityRequest): Promise<IdentityResolveResponse>;
+/**
+ * Capability-token refresh scheduler.
+ *
+ * Long-lived `@ablo/sync-engine` clients hold a server-issued capability
+ * token whose TTL (1h default) is shorter than typical browser sessions.
+ * Without proactive refresh, the WebSocket would either be force-closed
+ * by the server at expiry (code 1008) or fail its next reconnect with
+ * 401. Either way the user sees a mid-session disconnect.
+ *
+ * This scheduler keeps the token fresh transparently. Three triggers,
+ * one refresh path:
+ *
+ *   1. Proactive  — `setTimeout` for `(expiresAtMs - bufferMs - now)`.
+ *   2. Visibility — on `document.visibilitychange→visible`, if the
+ *                   token is within the buffer window, refresh now.
+ *                   Defends against dormant-tab `setTimeout` throttling.
+ *   3. Reactive   — caller invokes `.refreshNow()` on observed auth
+ *                   failure (WS close 1008/4001 etc).
+ *
+ * All three resolve through the same `inFlight` promise so concurrent
+ * triggers don't double-mint. On any successful refresh the new
+ * `expiresAtMs` is captured and trigger 1 is rescheduled.
+ *
+ * Buffer policy: `max(60s, ttl/10)` — for a 1h TTL that's 360s, which
+ * matches the AWS SDK / MSAL.js de-facto 5-minute standard while
+ * scaling sensibly for shorter TTLs.
+ */
+export interface RefreshSchedulerOptions {
+    /** Initial absolute expiry, ms since epoch (server-supplied). */
+    readonly initialExpiresAtMs: number;
+    /**
+     * Performs the actual exchange. Returns the new expiry. Errors
+     * propagate to `onError`; the scheduler stays alive and retries on
+     * next trigger (no exponential backoff in v1 — most failures here are
+     * the user's apiKey being revoked, in which case retrying is futile).
+     */
+    readonly refresh: () => Promise<{
+        expiresAtMs: number;
+    }>;
+    /** Called on every successful refresh. */
+    readonly onRefreshed?: (info: {
+        expiresAtMs: number;
+    }) => void;
+    /** Called on every refresh failure. */
+    readonly onError?: (error: Error) => void;
+    /**
+     * Override the buffer (ms ahead of expiry to refresh). Defaults to
+     * `max(60_000, ttlMs * 0.1)`. Tests use a tiny value to exercise
+     * scheduling without burning real time.
+     */
+    readonly bufferMs?: number;
+    /**
+     * If true, install a `visibilitychange` listener on `document` that
+     * triggers a refresh when the tab becomes visible and the token is
+     * within the buffer window. No-op if `document` is undefined (Node).
+     * Default: true in browser-ish environments.
+     */
+    readonly attachVisibilityListener?: boolean;
+    /** Time source. Override in tests; defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** Timer pair. Override in tests. */
+    readonly setTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    readonly clearTimer?: (handle: ReturnType<typeof setTimeout>) => void;
+}
+export interface RefreshScheduler {
+    /** Force a refresh now. Idempotent — concurrent calls share one promise. */
+    refreshNow(): Promise<{
+        expiresAtMs: number;
+    }>;
+    /** Stop scheduling. Safe to call multiple times. */
+    dispose(): void;
+    /** Current absolute expiry. Updated after each successful refresh. */
+    readonly expiresAtMs: number;
+}
+export declare function createRefreshScheduler(options: RefreshSchedulerOptions): RefreshScheduler;