@abloatai/ablo 0.17.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;
     /**
@@ -133,6 +134,22 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * @default 'websocket'
      */
     transport?: 'websocket' | 'http' | undefined;
+    /**
+     * Turn Ablo's diagnostic logging on/off. `true` surfaces the `[Ablo]`
+     * coordination trace — claims requested / queued / granted / released, agent
+     * handovers, connection state — so you can SEE the human+agent coordination
+     * you built while debugging. Omitted/`false` keeps the quiet default (only
+     * warnings + errors). For a middle ground use {@link logLevel}. Env override:
+     * `ABLO_LOG_LEVEL`. Ignored if a custom logger is supplied.
+     */
+    debug?: boolean | undefined;
+    /**
+     * Log threshold for the default `[Ablo]` logger (takes precedence over
+     * {@link debug}). `'info'` = coordination + connection events without the
+     * per-model registration firehose; `'debug'` = everything; `'warn'` (default)
+     * = warnings + errors only; `'silent'` = nothing. Env override: `ABLO_LOG_LEVEL`.
+     */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent' | undefined;
     /**
      * Bearer auth token. Hosted-cloud consumers pass `apiKey`; self-hosted
      * deployments may pass a bearer token minted by their own auth layer.
@@ -242,8 +259,24 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * `apiKey` only; the server handles capability issuance.
      */
     capabilityToken?: string;
-    /** Custom logger (default: console) */
+    /** Custom logger (default: console). Supplying one bypasses {@link debug}/{@link logLevel}. */
     logger?: SyncLogger;
+    /**
+     * Turn Ablo's diagnostic logging on/off. `true` surfaces the `[Ablo]`
+     * coordination trace — claims acquired / queued / granted / released, agent
+     * handovers, connection state — plus internal lifecycle, so you can SEE the
+     * human+agent coordination you built. Omitted/`false` keeps the quiet default
+     * (only warnings + errors). For a middle ground use {@link logLevel}.
+     * Env override: `ABLO_LOG_LEVEL`. Ignored if a custom {@link logger} is passed.
+     */
+    debug?: boolean;
+    /**
+     * Log threshold for the default `[Ablo]` logger (takes precedence over
+     * {@link debug}). `'info'` = coordination + connection events without the
+     * per-model registration firehose; `'debug'` = everything; `'warn'` (default)
+     * = warnings + errors only; `'silent'` = nothing. Env override: `ABLO_LOG_LEVEL`.
+     */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
     /** ObjectPool size limit (default: 10000) */
     maxPoolSize?: number;
     /**
@@ -371,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';
@@ -396,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;
     /**
@@ -442,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;
@@ -481,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>;
 }
@@ -493,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
@@ -511,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>> {
@@ -614,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 {
@@ -734,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:
@@ -975,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;
@@ -983,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>;
@@ -1021,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';
@@ -519,7 +519,17 @@ function createDynamicModelClass(modelName, jsonSubFields, fieldNames, computed,
     return ModelClass;
 }
 const LOG_LEVEL_RANK = { debug: 10, info: 20, warn: 30, error: 40, silent: 99 };
-function resolveLogLevel() {
+/**
+ * Resolve the effective level. Precedence: explicit `logLevel` option →
+ * `debug: true` (⇒ debug) → `ABLO_LOG_LEVEL` env → default `warn`. `debug: false`
+ * / omitted just means "don't raise the level" — it falls through to env/default
+ * rather than force-silencing an ops-set env override.
+ */
+function resolveLogLevel(opts) {
+    if (opts?.logLevel && opts.logLevel in LOG_LEVEL_RANK)
+        return opts.logLevel;
+    if (opts?.debug === true)
+        return 'debug';
     // `globalThis.process` guard keeps this safe in browser/edge runtimes that
     // have no `process` binding — there we fall through to the default.
     const raw = globalThis.process?.env?.ABLO_LOG_LEVEL;
@@ -528,12 +538,16 @@ function resolveLogLevel() {
         return normalized;
     return 'warn';
 }
-const consoleLogger = (() => {
-    const threshold = LOG_LEVEL_RANK[resolveLogLevel()];
-    const emit = (level, fn, args) => {
-        if (typeof console === 'undefined' || LOG_LEVEL_RANK[level] < threshold)
+/**
+ * Build the default logger, gated at `level` and prefixed `[Ablo]` so a creator
+ * with a console full of other tools' logs can see at a glance what's ours.
+ */
+function createConsoleLogger(level) {
+    const threshold = LOG_LEVEL_RANK[level];
+    const emit = (lvl, fn, args) => {
+        if (typeof console === 'undefined' || LOG_LEVEL_RANK[lvl] < threshold)
             return;
-        fn('[sync]', ...args);
+        fn('[Ablo]', ...args);
     };
     return {
         debug: (...args) => emit('debug', console.debug, args),
@@ -541,7 +555,7 @@ const consoleLogger = (() => {
         warn: (...args) => emit('warn', console.warn, args),
         error: (...args) => emit('error', console.error, args),
     };
-})();
+}
 // `readProcessEnv` lives in `./auth` alongside the other resolvers
 // that read it. Re-exported there for use elsewhere in the file.
 // ── Default mutation executor (wire: `commit` frame over WebSocket) ──────
@@ -725,10 +739,15 @@ export function Ablo(options) {
         databaseUrl: configuredDatabaseUrl,
         dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
     });
-    const { logger = consoleLogger } = internalOptions;
+    // Custom logger wins; otherwise build the default `[Ablo]` logger at the level
+    // resolved from `debug`/`logLevel`/`ABLO_LOG_LEVEL` (default `warn`).
+    const logger = internalOptions.logger ??
+        createConsoleLogger(resolveLogLevel({ debug: options.debug, logLevel: options.logLevel }));
     // 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
@@ -877,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).
@@ -1100,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;
@@ -1135,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,
@@ -1155,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,
@@ -1254,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,
@@ -1292,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,
                         }));
@@ -1301,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;
                     }
                 }
@@ -1413,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
@@ -1562,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,
@@ -1614,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>;
 }