@abloatai/ablo 0.18.0 → 0.19.0

package/dist/client/Ablo.d.ts

@@ -29,7 +29,7 @@ import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
 import type { SyncGroupInput } from '../schema/roles.js';
 import { type SyncStatus } from '../BaseSyncedStore.js';
 import type { ClaimStream, ClaimWaitOptions, PresenceStream, Snapshot } from '../types/streams.js';
-import type { ClaimHandle, Duration } from '../types/streams.js';
+import type { Claim, Duration } from '../types/streams.js';
 import { type AbloApi, type AbloApiClientOptions, type AbloApiClaims } from './ApiClient.js';
 import { type AbloHttpClient, type AbloHttpClientOptions } from './httpClient.js';
 /**
@@ -96,18 +96,19 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     apiKey?: string | ApiKeySetter | null | undefined;
     /**
-     * Direct-URL convenience connector: a connection string to your own Postgres
-     * that Ablo can register for a dedicated tenant.
+     * @deprecated The direct connector lets Ablo dial INTO your Postgres and write to
+     * it — the operate-their-database posture we are moving off. Ablo is Stripe-shaped:
+     * it hosts only the transaction log (the ordered sync_deltas) + coordination, never
+     * your data; your rows always live in your own database. Use the signed Data Source
+     * endpoint instead — keep `DATABASE_URL` in your app, expose `dataSource(...)`, and
+     * let your server own the write while Ablo coordinates the sync stream. To keep the
+     * log in your infra too, self-host the engine. See
+     * docs/plans/stripe-shaped-storage-posture.md.
      *
-     * This is NOT the default Data Source path. For the Zero-shaped default, keep
-     * `DATABASE_URL` in your app, expose `dataSource(...)`, and let your server
-     * write the database while Ablo coordinates the sync stream.
-     *
-     * SERVER-ONLY: this carries credentials, so it is never sent from the browser
-     * — constructing a client with `databaseUrl` and `dangerouslyAllowBrowser`
-     * throws. If you opt into this connector, provide a NON-superuser,
-     * non-`BYPASSRLS` role; the direct connector rejects privileged roles that
-     * cannot enforce RLS.
+     * Still honored at runtime for back-compat. SERVER-ONLY: it carries credentials, so
+     * it is never sent from the browser — constructing a client with `databaseUrl` and
+     * `dangerouslyAllowBrowser` throws. If you use it, provide a NON-superuser,
+     * non-`BYPASSRLS` role; the connector rejects privileged roles that cannot enforce RLS.
      */
     databaseUrl?: string | null | undefined;
     /**
@@ -403,7 +404,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
  *   `create({ data })` / `update({ id, data })` / `delete({ id })` — writes
  *   `claim({ id })` — durable claim handle for coordinated writes
  */
-export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelOperations, } from './createModelProxy.js';
+export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ModelOperations, } from './createModelProxy.js';
 import type { ModelOperations, ClaimOptions, ClaimParams, ClaimReadApi, AwaitedClaimMethod, ServerReadOptions } from './createModelProxy.js';
 export type ModelOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
 export type CommitWait = 'queued' | 'confirmed';
@@ -428,7 +429,7 @@ export interface ModelReadOptions extends ClaimedOptions {
 export interface ClaimCreateOptions {
     readonly target: ModelTarget;
     /** Human-readable phase shown to peers — `'editing'`, `'writing'`. The same
-     *  word on every claim surface; serialized on the wire as `action`. */
+     *  word on every claim surface. */
     readonly reason: string;
     readonly ttl?: Duration;
     /**
@@ -474,7 +475,7 @@ export interface CommitCreateOptions {
      * 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 claim?: Claim<Record<string, unknown>> | null;
     readonly operation?: CommitOperationInput;
     readonly operations?: readonly CommitOperationInput[];
     readonly wait?: CommitWait;
@@ -513,7 +514,7 @@ export interface CommitResource {
     create(options: CommitCreateOptions): Promise<CommitReceipt>;
 }
 export interface ClaimResource extends ClaimStream {
-    create(options: ClaimCreateOptions): Promise<ClaimHandle>;
+    create(options: ClaimCreateOptions): Promise<Claim>;
     list(target?: Partial<ModelTarget>): readonly ModelClaim[];
     waitFor(target: Partial<ModelTarget>, options?: ClaimWaitOptions): Promise<void>;
 }
@@ -525,7 +526,7 @@ export interface ModelMutationOptions extends ClaimedOptions {
     readonly readAt?: number | null;
     readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
     readonly wait?: CommitWait;
-    readonly claim?: ClaimHandle | ClaimOptions | null;
+    readonly claim?: Claim | ClaimOptions | null;
 }
 /**
  * The HTTP/stateless claim surface. Normal tools usually put `claim` directly
@@ -543,7 +544,7 @@ export interface ModelMutationOptions extends ClaimedOptions {
  * wrapper that statelessness forces. `claim({ id })` is identical (already async
  * on both); `state`/`queue`/`reorder`/`release` are the awaited form.
  */
-export type HttpClaimApi<T = Record<string, unknown>> = ((params: ClaimParams<T>) => Promise<ClaimHandle<T>>) & {
+export type HttpClaimApi<T = Record<string, unknown>> = ((params: ClaimParams<T>) => Promise<Claim<T>>) & {
     [K in keyof ClaimReadApi<T>]: AwaitedClaimMethod<ClaimReadApi<T>[K]>;
 };
 export interface ModelClient<T = Record<string, unknown>> {
@@ -646,6 +647,38 @@ export interface CreateAgentSessionParams<S extends SchemaRecord> {
  *  `{ user }` for a full-authority end-user session (`ek_`) or `{ agent, can }`
  *  for a scoped agent session (`rk_`). */
 export type CreateSessionParams<S extends SchemaRecord> = CreateUserSessionParams | CreateAgentSessionParams<S>;
+/** Params for {@link Ablo.agents}.create — a flattened agent descriptor (no
+ *  `{ agent }` discriminator: `agents.create` only ever mints an agent). Unlike
+ *  {@link CreateSessionParams} it resolves to a connected, scoped {@link Ablo}
+ *  client rather than a raw token. */
+export interface CreateAgentClientParams<S extends SchemaRecord> {
+    /** Wire participant identity (`agent:<id>`) — what claim exclusion and the
+     *  FIFO queue gate on. OMIT to get a fresh `crypto.randomUUID()`: a distinct,
+     *  independent participant (the default, and what you want for concurrent
+     *  agents). Pass a STABLE string only when one logical agent must re-attach
+     *  to its own held claims across reconnects/restarts. */
+    id?: string;
+    /** Human-readable label for logs / attribution (carried in `userMeta.name`).
+     *  INDEPENDENT of `id`: two agents that share a `name` still receive distinct
+     *  ids and coordinate as SEPARATE participants — `name` never derives or
+     *  collapses identity. */
+    name?: string;
+    /** Per-model operation allowlist, typed against the schema's model names. */
+    can: {
+        [M in keyof S & string]?: readonly SessionOperation[];
+    };
+    /** Sync groups this agent may subscribe to — typed (`'default'` or
+     *  `<namespace>:<id>`). Omit for the server default (org anchor + the
+     *  agent's own anchor). */
+    syncGroups?: readonly SyncGroupInput[];
+    /** Token lifetime in seconds. Defaults to 900 (15m); the returned client
+     *  auto-re-mints before expiry, so a long-running agent never handles
+     *  rotation itself. */
+    ttlSeconds?: number;
+    /** Extra opaque identity blob echoed on the session scope. Merged with
+     *  `name` (the `name` param wins if you also set `userMeta.name`). */
+    userMeta?: Record<string, unknown>;
+}
 /** A minted session token — the Stripe ephemeral-key / Supabase session
  *  resource. `token` is the secret the holder presents as its bearer. */
 export interface AbloSession {
@@ -766,6 +799,35 @@ export type Ablo<S extends SchemaRecord> = {
     sessions: {
         create(params: CreateSessionParams<S>): Promise<AbloSession>;
     };
+    /**
+     * Mint a scoped **agent identity** and return a ready-to-use client bound to
+     * it — the `ablo.<resource>.<verb>` shape for the agent use case. One call
+     * replaces `sessions.create({ agent })` + constructing a second
+     * `Ablo({ apiKey: token })`:
+     *
+     * ```ts
+     * const agent = await ablo.agents.create({
+     *   name: 'researcher',                  // readable label (optional)
+     *   can: { documents: ['read', 'update'] },
+     *   // id omitted → a fresh uuid: a distinct, independent participant
+     * });
+     * await agent.documents.update({ id, data, claim });
+     * await agent.dispose(); // when the agent is done
+     * ```
+     *
+     * Server-side only (requires the `sk_` secret key, like `sessions.create`);
+     * throws `AbloAuthenticationError` in the browser. The returned client holds
+     * its own auto-refreshing `rk_`, so a long run never hits token expiry, and
+     * the `sk_` never leaves this process. Each call is a DISTINCT participant by
+     * default (omit `id` → fresh uuid), so even two agents sharing a `name` queue
+     * behind one another on a contended row — `name` is display only and never
+     * collapses identity. Humans don't get a server-built client — ship them a
+     * token via `sessions.create({ user })`. Need the raw token for revocation,
+     * or a stable re-attachable id? Use `sessions.create({ agent })` / pass `id`.
+     */
+    agents: {
+        create(params: CreateAgentClientParams<S>): Promise<Ablo<S>>;
+    };
     /**
      * The organization this client resolved to — `null` until `ready()`
      * completes. Use it instead of scraping CLI output or hardcoding env vars:
@@ -1007,7 +1069,7 @@ export declare namespace Ablo {
     type RotatedCapability = import('./ApiClient.js').RotatedCapability;
     type IfClaimedPolicy = import('./Ablo.js').IfClaimedPolicy;
     type ClaimedOptions = import('./Ablo.js').ClaimedOptions;
-    type EntityRef = _Streams.EntityRef;
+    type ClaimTarget = _Streams.ClaimTarget;
     type PresenceTarget = _Streams.PresenceTarget;
     type TargetRange = _Streams.TargetRange;
     type Duration = _Streams.Duration;
@@ -1015,8 +1077,7 @@ export declare namespace Ablo {
     type ClaimStream = _Streams.ClaimStream;
     type Peer = _Streams.Peer;
     type Activity = _Streams.Activity;
-    type ActiveClaim = _Streams.ActiveClaim;
-    type ClaimHandle = _Streams.ClaimHandle;
+    type Claim = _Streams.Claim;
     type ClaimRejection = _Streams.ClaimRejection;
     type ClaimLost = _Streams.ClaimLost;
     type Snapshot<TSchema extends _SchemaTypes.Schema = _SchemaTypes.Schema, K extends keyof TSchema['models'] = keyof TSchema['models']> = _Streams.Snapshot<TSchema, K>;
@@ -1053,7 +1114,7 @@ export declare namespace Ablo {
         type Client = import('./Ablo.js').CommitResource;
     }
     namespace Claim {
-        type Handle = import('./Ablo.js').ClaimHandle;
+        type Handle = import('./Ablo.js').Claim;
         type CreateOptions = import('./Ablo.js').ClaimCreateOptions;
         type WaitOptions = import('./Ablo.js').ClaimWaitOptions;
         type Client = import('./Ablo.js').ClaimResource;

package/dist/client/Ablo.js

@@ -42,7 +42,7 @@ import { createProtocolClient, } from './ApiClient.js';
 // Value import is cycle-safe: httpClient.js only value-imports ApiClient.js,
 // which imports this module type-only.
 import { createAbloHttpClient, } from './httpClient.js';
-import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfDatabaseUrlEnvIgnored, } from './auth.js';
+import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfCliKeyMismatch, warnIfDatabaseUrlEnvIgnored, warnIfDatabaseUrlDeprecated, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
 import { shouldUseInMemoryPersistence, } from './persistence.js';
 import { createModelProxy } from './createModelProxy.js';
@@ -746,6 +746,8 @@ export function Ablo(options) {
     // Nudge (once) if a stray DATABASE_URL is in the env but `databaseUrl` wasn't
     // passed — the env value is no longer auto-adopted (see resolveDatabaseUrl).
     warnIfDatabaseUrlEnvIgnored(authInput, (m) => logger.warn(m));
+    warnIfDatabaseUrlDeprecated(authInput, (m) => logger.warn(m));
+    void warnIfCliKeyMismatch(authInput, (m) => logger.warn(m));
     const schema = options.schema;
     const url = resolveBaseURL(authInput);
     // 1. Derive config from schema
@@ -894,6 +896,19 @@ export function Ablo(options) {
         store.syncStatus.state = 'error';
         store.syncStatus.error = _validationError;
     }
+    // Deprecated identity overrides are a silent no-op under hosted cloud: when an
+    // `apiKey` is configured the SERVER derives participant kind + id from the
+    // key's scope, so `kind` / `agentId` passed here are ignored. Setting them and
+    // trusting them is the trap (you think you're an agent; the key says user).
+    // Warn loudly rather than removing the fields — `agentId` is still load-bearing
+    // on the self-hosted path (no apiKey; paired with `capabilityToken`).
+    if (configuredApiKey && (internalOptions.kind || internalOptions.agentId)) {
+        logger.warn('Ablo: `kind` / `agentId` are ignored when an `apiKey` is configured — ' +
+            'the server derives participant identity from the key’s scope. Remove ' +
+            'them (or mint a scoped session via `ablo.sessions.create({ agent })` ' +
+            'for a distinct agent identity). They apply only to the self-hosted ' +
+            '`capabilityToken` path.');
+    }
     // 7. The ready() promise drives the BaseSyncedStore.initialize() generator
     //    to completion. First call kicks off the initialization; subsequent
     //    calls return the same promise (idempotent).
@@ -1117,7 +1132,7 @@ export function Ablo(options) {
         return (typeof value === 'object' &&
             value !== null &&
             value.object === 'claim' &&
-            typeof value.claimId === 'string');
+            typeof value.id === 'string');
     }
     function normalizeCommitOperation(op, defaults) {
         const model = op.model ?? op.target?.model;
@@ -1152,13 +1167,13 @@ export function Ablo(options) {
         const description = descriptionFromMeta(claim.target.meta);
         return {
             id: claim.id,
-            actor: claim.heldBy,
-            participantKind: claim.participantKind,
+            actor: claim.heldBy ?? "",
+            participantKind: claim.participantKind ?? "user",
             reason: claim.reason,
             ...(description ? { description } : {}),
             field: claim.target.field,
             status: 'active',
-            expiresAt: claim.expiresAt,
+            expiresAt: claim.expiresAt ?? 0,
             target: {
                 model: claim.target.type,
                 id: claim.target.id,
@@ -1172,14 +1187,14 @@ export function Ablo(options) {
     function modelClaimFromQueued(claim) {
         return {
             id: claim.id,
-            actor: claim.heldBy,
-            participantKind: claim.participantKind,
+            actor: claim.heldBy ?? "",
+            participantKind: claim.participantKind ?? "user",
             reason: claim.reason,
             ...(claim.description ? { description: claim.description } : {}),
             field: claim.target.field,
             status: 'queued',
             position: claim.position,
-            expiresAt: claim.expiresAt,
+            expiresAt: claim.expiresAt ?? 0,
             target: {
                 model: claim.target.type,
                 id: claim.target.id,
@@ -1271,11 +1286,11 @@ export function Ablo(options) {
     }
     function wrapClaimHandle(claim, waited = false) {
         const release = async () => {
-            claim.revoke();
+            claim.revoke?.();
         };
         return {
             object: 'claim',
-            claimId: claim.claimId,
+            id: claim.id,
             reason: claim.reason,
             target: claim.target,
             waited,
@@ -1309,7 +1324,7 @@ export function Ablo(options) {
                 const ws = store.getSyncWebSocket();
                 if (ws) {
                     try {
-                        ({ waited } = await awaitClaimGrant(ws, claim.claimId, {
+                        ({ waited } = await awaitClaimGrant(ws, claim.id, {
                             timeoutMs: claimOptions.waitTimeoutMs,
                             maxQueueDepth: claimOptions.maxQueueDepth,
                         }));
@@ -1318,7 +1333,7 @@ export function Ablo(options) {
                         // Gave up waiting (queue too deep, timed out, or lost) — abandon
                         // the queued claim so we don't leave a phantom entry in the
                         // line that would block or mislead other claimers.
-                        claim.revoke();
+                        claim.revoke?.();
                         throw err;
                     }
                 }
@@ -1430,7 +1445,7 @@ export function Ablo(options) {
                 onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
             });
             const wait = commitOptions.wait ?? 'confirmed';
-            const claimId = normalizeClaimId(commitOptions.claimRef) ?? claim?.claimId;
+            const claimId = normalizeClaimId(commitOptions.claimRef) ?? claim?.id;
             void claimId; // The current wire clears claims by entity after commit.
             // Route through the TransactionQueue's commit lane so the call
             // tolerates WS disconnects: the envelope stays in memory until
@@ -1579,6 +1594,34 @@ export function Ablo(options) {
     async function controlPlaneApiKey() {
         return resolveApiKeyValue(configuredApiKey);
     }
+    /**
+     * Resolve the control-plane context a session/agent mint needs (sk_ +
+     * bootstrap base URL + the schema-key→typename map the Hub gates on).
+     * Shared by `sessions.create` and `agents.create` so the two mint doors
+     * can never drift on how a token is minted. Throws if no `sk_` is present —
+     * minting is a backend-only operation.
+     */
+    async function buildMintContext(resource) {
+        const apiKey = await controlPlaneApiKey();
+        if (!apiKey) {
+            throw new AbloAuthenticationError(`${resource} requires a secret (sk_) API key — call it from your backend, not the browser.`, { code: 'apikey_missing' });
+        }
+        return {
+            apiKey,
+            baseUrl: resolveBootstrapBaseUrl({
+                url,
+                bootstrapBaseUrl: internalOptions.bootstrapBaseUrl,
+            }),
+            ...(internalOptions.fetch ? { fetch: internalOptions.fetch } : {}),
+            // Map every `can` schema-key to the wire typename the Hub gates on, so a
+            // typename override (`documents` → `Document`) doesn't mint a capability
+            // the server then denies. See `MintSessionContext`.
+            modelTypenames: Object.fromEntries(Object.entries(schema.models).map(([key, def]) => [
+                key,
+                def.typename ?? key,
+            ])),
+        };
+    }
     const engine = {
         ...modelProxies,
         ready,
@@ -1631,23 +1674,53 @@ export function Ablo(options) {
             // agent credential silently replacing the secret key on control-plane
             // calls is how humans get minted as agents — attribution is the product.
             async create(params) {
-                const apiKey = await controlPlaneApiKey();
-                if (!apiKey) {
-                    throw new AbloAuthenticationError('sessions.create requires a secret (sk_) API key — call it from your backend, not the browser.', { code: 'apikey_missing' });
-                }
-                const baseUrl = resolveBootstrapBaseUrl({
-                    url,
-                    bootstrapBaseUrl: internalOptions.bootstrapBaseUrl,
-                });
-                // The two mint doors (`{ user }` → /auth/ephemeral-keys → `ek_`,
-                // `{ agent, can }` → /auth/capability → scoped `rk_`) live in the shared
-                // `mintSession` so this stateful client and the stateless HTTP client can
-                // never drift on how a token is minted.
-                return mintSession(params, {
-                    apiKey,
-                    baseUrl,
-                    ...(internalOptions.fetch ? { fetch: internalOptions.fetch } : {}),
-                });
+                // Both mint doors (`{ user }` → /auth/ephemeral-keys → `ek_`,
+                // `{ agent, can }` → /auth/capability → scoped `rk_`) resolve their
+                // control-plane context through the shared `buildMintContext`, so this
+                // client, `agents.create`, and the stateless HTTP client can never drift
+                // on how a token is minted.
+                return mintSession(params, await buildMintContext('sessions.create'));
+            },
+        },
+        // Mint a scoped agent IDENTITY and hand back a connected client bound to it
+        // — `sessions.create({ agent })` + `Ablo({ apiKey })` fused into one call,
+        // for agents that run in THIS (sk_-holding) process. Omitting `id` yields a
+        // fresh uuid per call, so concurrent agents are distinct participants that
+        // queue behind each other (even when they share a `name`). Humans don't get
+        // a server-built client — ship them a token via `sessions.create({ user })`.
+        agents: {
+            async create(params) {
+                // Distinct participant by default: omit `id` → a fresh uuid, so even two
+                // agents that share a `name` are INDEPENDENT participants and queue
+                // behind one another. `name` is display only (→ userMeta.name); it never
+                // derives the id. Pass an explicit `id` only to re-attach an agent to
+                // its own held claims.
+                const id = params.id ?? globalThis.crypto.randomUUID();
+                const userMeta = params.name !== undefined ? { ...params.userMeta, name: params.name } : params.userMeta;
+                const sessionParams = {
+                    agent: { id },
+                    can: params.can,
+                    ...(params.syncGroups ? { syncGroups: params.syncGroups } : {}),
+                    ...(params.ttlSeconds !== undefined ? { ttlSeconds: params.ttlSeconds } : {}),
+                    ...(userMeta ? { userMeta } : {}),
+                };
+                // Re-mint the `rk_` on every resolver call so a long-lived agent client
+                // never hits token expiry; the `sk_` stays in THIS process — the child
+                // only ever sees its own short-lived `rk_`.
+                const mintToken = async () => (await mintSession(sessionParams, await buildMintContext('agents.create')))
+                    .token;
+                // Mint once up front so a bad key / denied scope throws HERE, not later
+                // inside the child's bootstrap; reuse that first token, re-mint on refresh.
+                let pending = await mintToken();
+                const apiKey = async () => {
+                    if (pending !== null) {
+                        const token = pending;
+                        pending = null;
+                        return token;
+                    }
+                    return mintToken();
+                };
+                return Ablo({ ...internalOptions, apiKey });
             },
         },
         async dispose() {

package/dist/client/ApiClient.d.ts

@@ -7,14 +7,14 @@
  */
 import type { AbloOptions, CommitResource, ClaimCreateOptions, ClaimWaitOptions, ModelClient, ModelClaim, ModelTarget, CreateSessionParams, AbloSession } from './Ablo.js';
 import type { SchemaRecord } from '../schema/schema.js';
-import type { ClaimHandle } from './createModelProxy.js';
 import type { Duration } from '../utils/duration.js';
+import type { Claim } from '../types/streams.js';
 export type AbloApiClientOptions = Omit<AbloOptions, 'schema'> & {
     readonly schema?: null | undefined;
     readonly bootstrapBaseUrl?: string | undefined;
 };
 export interface AbloApiClaims {
-    create(options: ClaimCreateOptions): Promise<ClaimHandle>;
+    create(options: ClaimCreateOptions): Promise<Claim>;
     list(target?: Partial<ModelTarget>): Promise<readonly ModelClaim[]>;
     waitFor(target: Partial<ModelTarget>, options?: ClaimWaitOptions): Promise<void>;
 }

package/dist/client/ApiClient.js

@@ -6,23 +6,11 @@
  * nouns directly to HTTP routes on sync-server.
  */
 import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, claimedError, translateHttpError, } from '../errors.js';
-import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfDatabaseUrlEnvIgnored, } from './auth.js';
+import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfCliKeyMismatch, warnIfDatabaseUrlEnvIgnored, warnIfDatabaseUrlDeprecated, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
 import { toSeconds } from '../utils/duration.js';
 import { mintSession } from './sessionMint.js';
 import { assertWriteOptions } from './writeOptionsSchema.js';
-/**
- * The `/v1/claims` and model-query routes still emit the wire field `action`
- * for the claim phase; the public `Claim` / `ModelClaim` expose it as `reason`.
- * Heal on read so the SDK shape is consistent without a coordinated server
- * deploy — `reason ?? action`. When the server adopts `reason`, this is a no-op.
- */
-function healClaimPhase(claim) {
-    const raw = claim;
-    if (raw.reason !== undefined)
-        return claim;
-    return { ...claim, reason: raw.action ?? 'editing' };
-}
 const DEFAULT_AGENT_LEASE = '10m';
 export function createProtocolClient(options) {
     const env = readProcessEnv();
@@ -33,6 +21,8 @@ export function createProtocolClient(options) {
     // Nudge (once) if a stray DATABASE_URL is in the env but `databaseUrl` wasn't
     // passed — no logger on this path, so the helper falls back to console.warn.
     warnIfDatabaseUrlEnvIgnored(authInput);
+    warnIfDatabaseUrlDeprecated(authInput);
+    void warnIfCliKeyMismatch(authInput);
     assertBrowserSafety({
         apiKey: configuredApiKey,
         databaseUrl: configuredDatabaseUrl,
@@ -185,8 +175,8 @@ export function createProtocolClient(options) {
         const suffix = params.toString();
         const body = await requestJson(`/v1/claims${suffix ? `?${suffix}` : ''}`, { method: 'GET' });
         return {
-            active: (body.claims ?? []).map(healClaimPhase),
-            queue: (body.queue ?? []).map(healClaimPhase),
+            active: body.claims ?? [],
+            queue: body.queue ?? [],
         };
     }
     function delay(ms, signal) {
@@ -272,7 +262,7 @@ export function createProtocolClient(options) {
                 body: JSON.stringify({
                     clientTxId,
                     idempotencyKey: clientTxId,
-                    claim: normalizeClaimId(commitOptions.claimRef) ?? claim?.claimId,
+                    claim: normalizeClaimId(commitOptions.claimRef) ?? claim?.id,
                     operations,
                 }),
             });
@@ -389,8 +379,7 @@ export function createProtocolClient(options) {
                 body: JSON.stringify({
                     claimId,
                     target: claimOptions.target,
-                    // Wire field stays `action`; public option is `reason`.
-                    action: claimOptions.reason,
+                    reason: claimOptions.reason,
                     ttl: claimOptions.ttl,
                     queue: claimOptions.queue,
                 }),
@@ -415,9 +404,16 @@ export function createProtocolClient(options) {
             };
             return {
                 object: 'claim',
-                claimId: id,
+                id,
                 reason: claimOptions.reason,
-                target: claimOptions.target,
+                target: {
+                    type: claimOptions.target.model,
+                    id: claimOptions.target.id,
+                    ...(claimOptions.target.field ? { field: claimOptions.target.field } : {}),
+                    ...(claimOptions.target.path ? { path: claimOptions.target.path } : {}),
+                    ...(claimOptions.target.range ? { range: claimOptions.target.range } : {}),
+                    ...(claimOptions.target.meta ? { meta: claimOptions.target.meta } : {}),
+                },
                 release,
                 revoke: () => {
                     void release().catch(() => { });
@@ -467,7 +463,7 @@ export function createProtocolClient(options) {
         return {
             data,
             stamp: query.stamp ?? 0,
-            claims: (query.claims ?? []).map(healClaimPhase),
+            claims: query.claims ?? [],
         };
     }
     /**
@@ -501,13 +497,13 @@ export function createProtocolClient(options) {
         const claimHandle = typeof options?.claim === 'object' &&
             options?.claim !== null &&
             options.claim.object === 'claim' &&
-            typeof options.claim.claimId === 'string'
+            typeof options.claim.id === 'string'
             ? options.claim
             : undefined;
         const readAt = options?.readAt ?? claimHandle?.readAt;
         const requestBody = {
             idempotencyKey: clientTxId,
-            claim: normalizeClaimId(options?.claimRef) ?? claimHandle?.claimId,
+            claim: normalizeClaimId(options?.claimRef) ?? claimHandle?.id,
             onStale: options?.onStale ?? (claimHandle?.readAt !== undefined ? 'reject' : undefined),
             readAt,
         };
@@ -538,7 +534,7 @@ export function createProtocolClient(options) {
         const isClaimHandle = (value) => typeof value === 'object' &&
             value !== null &&
             value.object === 'claim' &&
-            typeof value.claimId === 'string' &&
+            typeof value.id === 'string' &&
             typeof value.release === 'function';
         const claimMeta = (options) => {
             if (!options?.description)
@@ -549,8 +545,7 @@ export function createProtocolClient(options) {
             const body = await requestJson(claimPath(params.id), {
                 method: 'POST',
                 body: JSON.stringify({
-                    // Wire field stays `action`; public option is `reason`.
-                    action: params.reason ?? 'editing',
+                    reason: params.reason ?? 'editing',
                     ...(params.ttl !== undefined ? { ttl: params.ttl } : {}),
                     ...(params.description !== undefined ? { description: params.description } : {}),
                     ...(claimMeta(params) ? { meta: claimMeta(params) } : {}),
@@ -563,7 +558,7 @@ export function createProtocolClient(options) {
                 throw new AbloClaimedError(`Target ${name}/${params.id} is held; queued at position ${body.position ?? 0}. ` +
                     `The HTTP client cannot await the grant without a WebSocket.`, { code: 'claim_queued' });
             }
-            return body.claim?.id ?? body.id ?? body.claimId ?? createClaimId();
+            return body.claim?.id ?? body.id ?? body.id ?? createClaimId();
         };
         const releaseClaim = (params) => requestJson(claimPath(isClaimHandle(params) ? params.target.id : params.id), { method: 'DELETE' }).then(() => undefined);
         async function claimImpl(params) {
@@ -572,10 +567,10 @@ export function createProtocolClient(options) {
             const release = () => releaseClaim(params);
             return {
                 object: 'claim',
-                claimId,
+                id: claimId,
                 readAt: stamp,
                 target: {
-                    model: name,
+                    type: name,
                     id: params.id,
                     ...(params.field ? { field: params.field } : {}),
                     ...(params.path ? { path: params.path } : {}),
@@ -598,11 +593,11 @@ export function createProtocolClient(options) {
             state: async (params) => {
                 const res = await claimsForEntity(params);
                 const first = res.claims?.[0];
-                return first ? healClaimPhase(first) : null;
+                return first ?? null;
             },
             queue: async (params) => {
                 const res = await claimsForEntity(params);
-                return { object: 'list', data: (res.queue ?? []).map(healClaimPhase) };
+                return { object: 'list', data: res.queue ?? [] };
             },
             reorder: async (params) => {
                 await requestJson(`${claimPath(params.id)}/reorder`, {
@@ -618,7 +613,7 @@ export function createProtocolClient(options) {
             if (!claimInput)
                 return run(input);
             if (isClaimHandle(claimInput)) {
-                return run({ ...input, claimRef: { id: claimInput.claimId }, claim: undefined });
+                return run({ ...input, claimRef: { id: claimInput.id }, claim: undefined });
             }
             const claimId = await acquireClaim({ id, ...claimInput });
             try {

package/dist/client/auth.d.ts

@@ -49,6 +49,29 @@ export interface AuthResolveInput {
 export declare function readProcessEnv(): Record<string, string | undefined>;
 export declare function resolveApiKey(input: AuthResolveInput): string | ApiKeySetter | null;
 export declare function resolveAuthToken(input: AuthResolveInput): string | null;
+type CliMode = 'sandbox' | 'production';
+type StaticApiKeySource = 'option' | 'env';
+interface StaticApiKey {
+    readonly key: string;
+    readonly source: StaticApiKeySource;
+}
+interface CliCredentialSnapshot {
+    readonly mode: CliMode;
+    readonly activeProfile: string;
+    readonly storedKey?: string;
+}
+export interface CliKeyMismatch {
+    readonly source: StaticApiKeySource;
+    readonly configuredKeyPrefix: string;
+    readonly configuredMode?: CliMode;
+    readonly cliMode: CliMode;
+    readonly storedKeyPrefix?: string;
+    readonly kind: 'mode_mismatch' | 'key_override';
+    readonly message: string;
+}
+/** Infer sandbox/production from Ablo key prefixes without importing CLI code. */
+export declare function modeFromApiKey(key: string): CliMode | undefined;
+export declare function describeCliKeyMismatch(configured: StaticApiKey, cli: CliCredentialSnapshot): CliKeyMismatch | null;
 /**
  * Resolve the direct-URL connector's Postgres connection string.
  *
@@ -63,6 +86,8 @@ export declare function resolveAuthToken(input: AuthResolveInput): string | null
  */
 export declare function resolveDatabaseUrl(input: AuthResolveInput): string | null;
 export declare function warnIfDatabaseUrlEnvIgnored(input: AuthResolveInput, warn?: (message: string) => void): void;
+export declare function warnIfDatabaseUrlDeprecated(input: AuthResolveInput, warn?: (message: string) => void): void;
+export declare function warnIfCliKeyMismatch(input: AuthResolveInput, warn?: (message: string) => void): Promise<void>;
 export declare const ABLO_HOSTED_API_DOMAIN = "api.abloatai.com";
 export declare const ABLO_HOSTED_HTTP_BASE_URL = "https://api.abloatai.com";
 export declare const ABLO_DEFAULT_BASE_URL = "https://api.abloatai.com";
@@ -108,3 +133,4 @@ export declare function resolveBootstrapBaseUrl(input: {
     readonly url: string;
     readonly bootstrapBaseUrl?: string;
 }): string;
+export {};