@abloatai/ablo 0.9.1 → 0.9.3

package/dist/client/Ablo.d.ts

@@ -28,22 +28,6 @@ import type { IntentStream, IntentWaitOptions, PresenceStream, Snapshot } from '
 import type { ParticipantManager } from '../sync/participants.js';
 import type { ActiveIntent, Duration, Intent, TargetRange } from '../types/streams.js';
 import { type AbloApi, type AbloApiClientOptions, type AbloApiIntents } from './ApiClient.js';
-/**
- * Handle returned by `engine.beginTurn()`. While alive, every commit
- * automatically carries this turn's id on the wire. Call `close(stats?)`
- * when the turn finishes, or `dispose()` to abandon without recording
- * usage. Idempotent.
- */
-export interface Turn {
-    readonly turnId: string;
-    close(stats?: {
-        readonly costInputTokens?: number;
-        readonly costOutputTokens?: number;
-        readonly costComputeMs?: number;
-    }): Promise<void>;
-    dispose(): void;
-    [Symbol.asyncDispose](): Promise<void>;
-}
 /**
  * Async function that resolves an apiKey at request time. Use for
  * credential rotation — rotate from a vault, refresh from session
@@ -137,7 +121,7 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * Local persistence mode. Pass `indexeddb` only when you want offline
      * queueing and a reload-surviving browser cache.
      *
-     * @default 'volatile'
+     * @default 'memory'
      */
     persistence?: AbloPersistence;
     /**
@@ -266,7 +250,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     /** ObjectPool size limit (default: 10000) */
     maxPoolSize?: number;
     /**
-     * Local persistence mode. Defaults to `volatile` so Ablo behaves like a
+     * Local persistence mode. Defaults to `memory` so Ablo behaves like a
      * point solution for shared state instead of silently bolting IndexedDB
      * durability onto every browser consumer.
      *
@@ -278,7 +262,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     offline?: boolean;
     /**
      * @deprecated Internal/testing escape hatch. Use `persistence` in
-     * production code. `true` maps to `volatile`; `false` maps to
+     * production code. `true` maps to `memory`; `false` maps to
      * `indexeddb` in browsers.
      */
     inMemory?: boolean;
@@ -479,6 +463,15 @@ export interface CommitCreateOptions {
     readonly idempotencyKey?: string | null;
     readonly readAt?: number | null;
     readonly onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    /**
+     * A claim handle from `ablo.<model>.claim({ id })` (or the HTTP claim
+     * surface). Same vocabulary as the per-model writes: the handle's
+     * snapshot watermark becomes the batch `readAt` default and `onStale`
+     * defaults to `'reject'`, so a commit that follows a claim is guarded
+     * against concurrent edits without re-stating the watermark by hand.
+     * Explicit `readAt`/`onStale` on the options win.
+     */
+    readonly claim?: ClaimHandle<Record<string, unknown>> | null;
     readonly operation?: CommitOperationInput;
     readonly operations?: readonly CommitOperationInput[];
     readonly wait?: CommitWait;
@@ -809,10 +802,13 @@ export type Ablo<S extends SchemaRecord> = {
      */
     readonly presence: PresenceStream;
     /**
-     * Cooperative-mutex layer over presence — announce "I'm about to do
-     * X on Y" so peers can yield before colliding. Server enforces the
-     * mutex; rejected announcements surface via `intents.onRejected(...)`.
-     * Same socket as entity sync, no second connection.
+     * @internal — the public coordination API is `ablo.<model>.claim`. This
+     * accessor is the internal stream `claim` is built on; it is NOT part of the
+     * supported public surface and will be moved off the public type (it currently
+     * stays only because internal SDK modules are still typed against it).
+     *
+     * Cooperative-mutex layer over presence — announce "I'm about to do X on Y" so
+     * peers can yield before colliding. Same socket as entity sync.
      */
     readonly intents: IntentResource;
     /**
@@ -861,18 +857,6 @@ export type Ablo<S extends SchemaRecord> = {
     snapshot<ModelName extends keyof S & string>(entities: {
         readonly [M in ModelName]: string | readonly string[];
     }): Snapshot<Schema<S>, ModelName>;
-    /**
-     * Open a turn — every commit issued while the returned handle is
-     * alive carries `caused_by_task_id` on the wire so the server
-     * stamps it onto each delta. Powers `agent_tasks` audit trails.
-     * Server: `POST /api/agent/turn` with the capability bearer.
-     */
-    beginTurn(options: {
-        readonly prompt: string;
-        readonly parentTaskId?: string;
-        readonly surface?: string;
-        readonly metadata?: Record<string, unknown>;
-    }): Promise<Turn>;
     /**
      * The internal BaseSyncedStore. Implements SyncStoreContract — pass to
      * SyncContext.Provider so the SDK's useModel/useModels/useMutations hooks
@@ -973,17 +957,6 @@ export declare namespace Ablo {
     type Options<S extends SchemaRecord = SchemaRecord> = AbloOptions<S>;
     type Api = AbloApi;
     type ApiIntents = AbloApiIntents;
-    type Agent = import('./ApiClient.js').Agent;
-    type AgentOptions = import('./ApiClient.js').AgentOptions;
-    type AgentRunOptions = import('./ApiClient.js').AgentRunOptions;
-    type AgentRunStatus = import('./ApiClient.js').AgentRunStatus;
-    type AgentRunResult<T> = import('./ApiClient.js').AgentRunResult<T>;
-    type AgentRunContext = import('./ApiClient.js').AgentRunContext;
-    type AgentModelClient<T = Record<string, unknown>> = import('./ApiClient.js').AgentModelClient<T>;
-    type AgentModelReadOptions = import('./ApiClient.js').AgentModelReadOptions;
-    type AgentModelMutationOptions = import('./ApiClient.js').AgentModelMutationOptions;
-    type AgentIntentOptions = import('./ApiClient.js').AgentIntentOptions;
-    type AgentIntentInput = import('./ApiClient.js').AgentIntentInput;
     type Capability = import('./ApiClient.js').Capability;
     type CapabilityCreateOptions = import('./ApiClient.js').CapabilityCreateOptions;
     type CapabilityRecord = import('./ApiClient.js').CapabilityRecord;
@@ -991,11 +964,6 @@ export declare namespace Ablo {
     type CapabilityRevocation = import('./ApiClient.js').CapabilityRevocation;
     type CapabilityRotateOptions = import('./ApiClient.js').CapabilityRotateOptions;
     type RotatedCapability = import('./ApiClient.js').RotatedCapability;
-    type Task = import('./ApiClient.js').Task;
-    type TaskCreateOptions = import('./ApiClient.js').TaskCreateOptions;
-    type TaskCloseOptions = import('./ApiClient.js').TaskCloseOptions;
-    type TaskCloseResult = import('./ApiClient.js').TaskCloseResult;
-    type TaskResource = import('./ApiClient.js').TaskResource;
     type IfClaimedPolicy = import('./Ablo.js').IfClaimedPolicy;
     type ClaimedOptions = import('./Ablo.js').ClaimedOptions;
     type EntityRef = _Streams.EntityRef;
@@ -1011,7 +979,6 @@ export declare namespace Ablo {
     type IntentRejection = _Streams.IntentRejection;
     type IntentLost = _Streams.IntentLost;
     type Snapshot<TSchema extends _SchemaTypes.Schema = _SchemaTypes.Schema, K extends keyof TSchema['models'] = keyof TSchema['models']> = _Streams.Snapshot<TSchema, K>;
-    type Turn = import('./Ablo.js').Turn;
     namespace Auth {
         type Principal = _Streams.Principal;
         type Session = _Streams.SessionRef;

package/dist/client/Ablo.js

@@ -19,7 +19,7 @@
  *   await sync.reports.delete({ id: reportId });
  */
 import { z } from 'zod';
-import { AbloClaimedError, AbloError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, translateHttpError, hasWireCode, toAbloError } from '../errors.js';
+import { AbloClaimedError, AbloError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, translateHttpError, toAbloError } from '../errors.js';
 import { LoadStrategy, PropertyType } from '../types/index.js';
 import { initSyncEngine } from '../context.js';
 import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, noopAnalytics, } from '../SyncEngineContext.js';
@@ -41,6 +41,7 @@ import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue,
 import { registerDataSource } from './registerDataSource.js';
 import { shouldUseInMemoryPersistence, } from './persistence.js';
 import { createModelProxy } from './createModelProxy.js';
+import { assertWriteOptions } from './writeOptionsSchema.js';
 // ── Config derivation from schema ─────────────────────────────────────────
 /**
  * Compute a create-priority map from schema `belongsTo` relations using
@@ -812,13 +813,6 @@ export function Ablo(options) {
     // becomes null, so the first Ablo's commits start throwing
     // `ws_not_ready` forever (terminal AgentJob writes hang on retry).
     syncClient.getTransactionQueue().setMutationExecutor(executor);
-    // Active turn id, set by `beginTurn(...)`, cleared on close. While
-    // set, every batch commit attaches `causedByTaskId` so server
-    // delta rows get stamped with it. Single-turn-at-a-time per Ablo
-    // — opening a second turn overwrites the active id without closing
-    // the prior. Callers who need parallel turns construct multiple
-    // Ablo instances, matching the SyncAgent semantics.
-    let activeTurnId = null;
     // Presence + intent streams — built eagerly so `engine.presence`
     // and `engine.intents` return the same reference for the engine's
     // lifetime. The transport doesn't exist yet (BaseSyncedStore.initialize
@@ -1072,6 +1066,12 @@ export function Ablo(options) {
             return intent;
         return intent?.id;
     }
+    function isClaimHandleValue(value) {
+        return (typeof value === 'object' &&
+            value !== null &&
+            value.object === 'claim' &&
+            typeof value.claimId === 'string');
+    }
     function normalizeCommitOperation(op, defaults) {
         const model = op.model ?? op.target?.model;
         if (!model) {
@@ -1348,10 +1348,26 @@ export function Ablo(options) {
     const commits = {
         async create(commitOptions) {
             await ready();
+            // Same runtime contract as the per-model writes — one schema.
+            assertWriteOptions({
+                idempotencyKey: commitOptions.idempotencyKey,
+                readAt: commitOptions.readAt,
+                onStale: commitOptions.onStale,
+                wait: commitOptions.wait,
+                intent: commitOptions.intent,
+            }, 'commits.create');
             const clientTxId = createClientTxId(commitOptions.idempotencyKey);
-            const operations = normalizeCommitOperations(commitOptions);
+            // A claim handle supplies the batch stale-guard defaults — same
+            // semantics as `ablo.<model>.update({ id, data, claim })`, so the
+            // two write doors speak one claim vocabulary. Explicit options win.
+            const claim = commitOptions.claim ?? null;
+            const operations = normalizeCommitOperations({
+                ...commitOptions,
+                readAt: commitOptions.readAt ?? claim?.readAt ?? null,
+                onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
+            });
             const wait = commitOptions.wait ?? 'confirmed';
-            const intentId = normalizeIntentId(commitOptions.intent);
+            const intentId = normalizeIntentId(commitOptions.intent) ?? claim?.claimId;
             void intentId; // The current wire clears intents by entity after commit.
             // Route through the TransactionQueue's commit lane so the call
             // tolerates WS disconnects: the envelope stays in memory until
@@ -1363,9 +1379,7 @@ export function Ablo(options) {
             // SyncClient we already hold from createInternalComponents —
             // no need to leak an accessor through BaseSyncedStore.
             const queue = syncClient.getTransactionQueue();
-            queue.enqueueCommit(clientTxId, operations, {
-                causedByTaskId: activeTurnId,
-            });
+            queue.enqueueCommit(clientTxId, operations);
             if (wait === 'queued') {
                 return { id: clientTxId, status: 'queued' };
             }
@@ -1431,6 +1445,7 @@ export function Ablo(options) {
                     idempotencyKey: params.idempotencyKey,
                     readAt: params.readAt,
                     onStale: params.onStale,
+                    ...(isClaimHandleValue(params.claim) ? { claim: params.claim } : {}),
                     wait: params.wait,
                     operations: [
                         {
@@ -1449,6 +1464,7 @@ export function Ablo(options) {
                     idempotencyKey: params.idempotencyKey,
                     readAt: params.readAt,
                     onStale: params.onStale,
+                    ...(isClaimHandleValue(params.claim) ? { claim: params.claim } : {}),
                     wait: params.wait,
                     operations: [
                         {
@@ -1467,6 +1483,7 @@ export function Ablo(options) {
                     idempotencyKey: params.idempotencyKey,
                     readAt: params.readAt,
                     onStale: params.onStale,
+                    ...(isClaimHandleValue(params.claim) ? { claim: params.claim } : {}),
                     wait: params.wait,
                     operations: [
                         {
@@ -1638,99 +1655,6 @@ export function Ablo(options) {
                 entities,
             });
         },
-        // ── Turn handles ────────────────────────────────────────────────
-        //
-        // Open a turn — every commit issued while the returned handle is
-        // alive carries `caused_by_task_id` on the wire so the server
-        // stamps it onto each delta. The product surface this powers:
-        // `agent_tasks` audit trails ("which AI prompt produced this
-        // mutation"), parent/child turn chains, cost accounting per turn.
-        //
-        // POST /api/agent/turn (capability bearer) → returns turnId.
-        // POST /api/agent/turn/:id/close (capability bearer) → records
-        //   final cost stats. Idempotent.
-        async beginTurn(beginOptions) {
-            const baseUrl = url.replace(/\/+$/, '');
-            const turnUrl = `${baseUrl.replace(/^ws/, 'http')}/api/agent/turn`;
-            const headers = authCredentials.withAuthHeaders({ 'Content-Type': 'application/json' });
-            const res = await fetch(turnUrl, {
-                method: 'POST',
-                headers,
-                body: JSON.stringify({
-                    prompt: beginOptions.prompt,
-                    parentTaskId: beginOptions.parentTaskId,
-                    surface: beginOptions.surface,
-                    metadata: beginOptions.metadata,
-                }),
-            });
-            if (!res.ok) {
-                const text = await res.text().catch(() => '');
-                let parsed = text;
-                if (text) {
-                    try {
-                        parsed = JSON.parse(text);
-                    }
-                    catch {
-                        /* keep raw text */
-                    }
-                }
-                // Preserve the server's structured envelope (code/message/doc_url) when
-                // present; fall back to turn_open_failed for a bare/non-Ablo body.
-                throw hasWireCode(parsed)
-                    ? translateHttpError(res.status, parsed, res.headers.get('x-request-id') ?? undefined)
-                    : new AbloError(`beginTurn failed: ${res.status} ${text}`, {
-                        code: 'turn_open_failed',
-                        httpStatus: res.status,
-                    });
-            }
-            const json = (await res.json());
-            const turnId = json.turnId;
-            activeTurnId = turnId;
-            let closed = false;
-            const close = async (stats) => {
-                if (closed)
-                    return;
-                closed = true;
-                if (activeTurnId === turnId)
-                    activeTurnId = null;
-                const closeUrl = `${turnUrl}/${encodeURIComponent(turnId)}/close`;
-                const closeRes = await fetch(closeUrl, {
-                    method: 'POST',
-                    headers,
-                    body: JSON.stringify({
-                        costInputTokens: stats?.costInputTokens ?? 0,
-                        costOutputTokens: stats?.costOutputTokens ?? 0,
-                        costComputeMs: stats?.costComputeMs ?? 0,
-                    }),
-                });
-                if (!closeRes.ok) {
-                    const text = await closeRes.text().catch(() => '');
-                    let parsed = text;
-                    if (text) {
-                        try {
-                            parsed = JSON.parse(text);
-                        }
-                        catch {
-                            /* keep raw text */
-                        }
-                    }
-                    throw hasWireCode(parsed)
-                        ? translateHttpError(closeRes.status, parsed, closeRes.headers.get('x-request-id') ?? undefined)
-                        : new AbloError(`closeTurn failed: ${closeRes.status} ${text}`, {
-                            code: 'turn_close_failed',
-                            httpStatus: closeRes.status,
-                        });
-                }
-            };
-            const dispose = () => {
-                if (closed)
-                    return;
-                closed = true;
-                if (activeTurnId === turnId)
-                    activeTurnId = null;
-            };
-            return { turnId, close, dispose, [Symbol.asyncDispose]: () => close() };
-        },
     };
     return engine;
 }

package/dist/client/ApiClient.d.ts

@@ -5,7 +5,7 @@
  * IndexedDB, no WebSocket. It maps the public Model / Claim / Commit
  * nouns directly to HTTP routes on sync-server.
  */
-import type { AbloOptions, CommitReceipt, CommitResource, IntentCreateOptions, IntentHandle, IntentWaitOptions, ModelClient, ModelClaim, ModelMutationOptions, ModelReadOptions, ModelRead, ModelTarget, Turn } from './Ablo.js';
+import type { AbloOptions, CommitResource, IntentCreateOptions, IntentHandle, IntentWaitOptions, ModelClient, ModelClaim, ModelTarget } from './Ablo.js';
 import type { Duration } from '../utils/duration.js';
 export type AbloApiClientOptions = Omit<AbloOptions, 'schema'> & {
     readonly schema?: null | undefined;
@@ -115,127 +115,15 @@ export interface CapabilityResource {
      */
     mint(options: CapabilityCreateOptions): Promise<Capability>;
 }
-export interface TaskCreateOptions {
-    readonly prompt: string;
-    readonly parentTaskId?: string;
-    readonly surface?: string;
-    readonly metadata?: Record<string, unknown>;
-}
-export interface TaskCloseOptions {
-    readonly costInputTokens?: number;
-    readonly costOutputTokens?: number;
-    readonly costComputeMs?: number;
-}
-export interface Task {
-    readonly id: string;
-    readonly turnId: string;
-    readonly promptHash?: string;
-    readonly openedAt?: string;
-    close(stats?: TaskCloseOptions): Promise<TaskCloseResult>;
-}
-export interface TaskCloseResult {
-    readonly id: string;
-    readonly turnId: string;
-    readonly closed: boolean;
-    readonly alreadyClosed?: boolean;
-    readonly endedAt?: string;
-}
-export interface TaskResource {
-    create(options: TaskCreateOptions): Promise<Task>;
-    close(id: string, stats?: TaskCloseOptions): Promise<TaskCloseResult>;
-    /**
-     * Alias for `create`. Kept for the agent-run vocabulary; `create` is
-     * the canonical SDK verb.
-     */
-    open(options: TaskCreateOptions): Promise<Task>;
-}
-export interface AgentOptions {
-    readonly can: readonly string[];
-    readonly syncGroups?: readonly string[];
-    readonly label?: string;
-    readonly userMeta?: Record<string, unknown>;
-    /**
-     * Internal lease for the run capability. Most callers should omit it.
-     * The SDK revokes the capability when `run` finishes; the lease exists
-     * to clean up crashed or abandoned runs.
-     */
-    readonly lease?: Duration;
-    readonly leaseSeconds?: number;
-}
-export interface AgentRunOptions extends TaskCreateOptions {
-    readonly signal?: AbortSignal;
-    readonly costInputTokens?: number;
-    readonly costOutputTokens?: number;
-    readonly costComputeMs?: number;
-}
-export type AgentRunStatus = 'done' | 'failed' | 'cancelled';
-export interface AgentRunDone<T> {
-    readonly status: 'done';
-    readonly task: Task;
-    readonly value: T;
-}
-export interface AgentRunFailed {
-    readonly status: 'failed';
-    readonly task?: Task;
-    readonly error: unknown;
-}
-export interface AgentRunCancelled {
-    readonly status: 'cancelled';
-    readonly task?: Task;
-    readonly error?: unknown;
-}
-export type AgentRunResult<T> = AgentRunDone<T> | AgentRunFailed | AgentRunCancelled;
-export interface AgentIntentOptions {
-    readonly action: string;
-    readonly field?: string;
-    readonly ttl?: Duration;
-    readonly target?: Partial<ModelTarget>;
-}
-export type AgentIntentInput = string | AgentIntentOptions;
-export interface AgentModelReadOptions extends ModelReadOptions {
-}
-export interface AgentModelMutationOptions extends Omit<ModelMutationOptions, 'intent'> {
-    readonly intent?: AgentIntentInput | {
-        readonly id: string;
-    } | null;
-}
-export interface AgentModelClient<T = Record<string, unknown>> {
-    retrieve(params: AgentModelReadOptions & {
-        readonly id: string;
-    }): Promise<ModelRead<T>>;
-    create(params: AgentModelMutationOptions & {
-        readonly data: Record<string, unknown>;
-        readonly id?: string | null;
-    }): Promise<CommitReceipt>;
-    update(params: AgentModelMutationOptions & {
-        readonly id: string;
-        readonly data: Record<string, unknown>;
-    }): Promise<CommitReceipt>;
-    delete(params: AgentModelMutationOptions & {
-        readonly id: string;
-    }): Promise<CommitReceipt>;
-}
-export interface AgentRunContext {
-    readonly task: Task;
-    readonly ablo: AbloApi;
-    model<T = Record<string, unknown>>(name: string): AgentModelClient<T>;
-}
-export interface Agent {
-    readonly id: string;
-    run<T>(options: AgentRunOptions, handler: (context: AgentRunContext) => Promise<T> | T): Promise<AgentRunResult<T>>;
-}
 export interface AbloApi {
     ready(): Promise<void>;
     waitForFlush(): Promise<void>;
     dispose(): Promise<void>;
     purge(): Promise<void>;
     readonly capabilities: CapabilityResource;
-    readonly tasks: TaskResource;
     readonly intents: AbloApiIntents;
     readonly commits: CommitResource;
-    agent(id: string, options: AgentOptions): Agent;
     model<T = Record<string, unknown>>(name: string): ModelClient<T>;
-    beginTurn(options: TaskCreateOptions): Promise<Turn>;
     /**
      * Resolve the active bearer credential this client authenticates with — the
      * same token its own requests carry in `Authorization`. Returns `null` when