@abloatai/ablo 0.7.0 → 0.9.0

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

@@ -1,67 +1,76 @@
 /**
- * `@abloatai/ablo/ai-sdk` — multiplayer-with-AI as language model
- * middleware.
+ * Ablo + AI SDK tools.
  *
- * Two cross-cutting middlewares for any AI SDK consumer using
- * `streamText` / `generateText`:
+ * The base pattern is intentionally one object all the way down:
  *
- *   - `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`:
+ *   1. AI SDK `inputSchema` describes what the model may send.
+ *   2. `ablo.<model>.update({ id, data, claim })` performs the write.
+ *   3. `claim.description` tells humans and other agents what the tool is doing.
  *
  * ```ts
- * import { wrapLanguageModel, streamText } from 'ai';
- * import {
- *   intentBroadcastMiddleware,
- *   coordinationContextMiddleware,
- * } from '@abloatai/ablo/ai-sdk';
+ * import { tool, streamText } from 'ai';
+ * import { z } from 'zod';
  *
- * const target = { entityType: 'SlideDeck', entityId: 'deck-abc' };
+ * const renameTask = tool({
+ *   description: 'Rename a task.',
+ *   inputSchema: z.object({
+ *     id: z.string().describe('Task id'),
+ *     title: z.string().describe('New task title'),
+ *     description: z
+ *       .string()
+ *       .describe('Why this rename is being made'),
+ *   }),
+ *   execute: async ({ id, title, description }) => {
+ *     await ablo.tasks.update({
+ *       id,
+ *       data: { title },
+ *       wait: 'confirmed',
+ *       claim: {
+ *         field: 'title',
+ *         action: 'renaming',
+ *         description,
+ *       },
+ *     });
  *
- * const wrappedModel = wrapLanguageModel({
- *   model: anthropic('claude-opus-4-7'),
- *   middleware: [
- *     coordinationContextMiddleware({ agent, target }),
- *     intentBroadcastMiddleware({ agent, target }),
- *   ],
+ *     return { id, title };
+ *   },
  * });
  *
- * // Consumer keeps full control over messages, tools, system prompt:
- * const result = streamText({
- *   model: wrappedModel,
- *   messages: [...],
- *   tools: { ... },
- *   system: '...',
+ * await streamText({
+ *   model,
+ *   messages,
+ *   tools: { renameTask },
  * });
  * ```
  *
- * Or use the convenience composition for the common case:
+ * That is the common case. A claim passed directly to `update` is acquired,
+ * attached to the write, and released by the SDK.
  *
- * ```ts
- * import { wrapWithMultiplayer } from '@abloatai/ablo/ai-sdk';
+ * For multi-step tools, take one handle and release it when the tool is done:
  *
- * const wrappedModel = wrapWithMultiplayer({
- *   model: anthropic('claude-opus-4-7'),
- *   agent,
- *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
+ * ```ts
+ * const claim = await ablo.tasks.claim({
+ *   id,
+ *   action: 'rewriting',
+ *   description: 'Rewriting the task brief before updating follow-up fields.',
+ *   ttl: '2m',
  * });
+ *
+ * try {
+ *   await ablo.tasks.update({ id, data: { title }, claim });
+ *   await ablo.tasks.update({ id, data: { description: brief }, claim });
+ * } finally {
+ *   await claim.release();
+ * }
  * ```
  *
- * 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.
+ * `claim.state`, `claim.queue`, and `claim.reorder` are coordination reads and
+ * scheduler controls. They are useful for UI or operators, but normal AI tools
+ * should start with `update({ id, data, claim })` or a manual claim handle.
+ *
+ * `wrapWithMultiplayer` is optional. Use it when the whole model call is scoped
+ * to one entity before any tool is chosen; tool implementations stay exactly
+ * the same.
  */
 export { intentBroadcastMiddleware, type IntentTarget, type IntentBroadcastMiddlewareOptions, } from './intent-broadcast.js';
 export { coordinationContextMiddleware, type CoordinationContextMiddlewareOptions, } from './coordination-context.js';

package/dist/ai-sdk/index.js

@@ -1,67 +1,76 @@
 /**
- * `@abloatai/ablo/ai-sdk` — multiplayer-with-AI as language model
- * middleware.
+ * Ablo + AI SDK tools.
  *
- * Two cross-cutting middlewares for any AI SDK consumer using
- * `streamText` / `generateText`:
+ * The base pattern is intentionally one object all the way down:
  *
- *   - `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`:
+ *   1. AI SDK `inputSchema` describes what the model may send.
+ *   2. `ablo.<model>.update({ id, data, claim })` performs the write.
+ *   3. `claim.description` tells humans and other agents what the tool is doing.
  *
  * ```ts
- * import { wrapLanguageModel, streamText } from 'ai';
- * import {
- *   intentBroadcastMiddleware,
- *   coordinationContextMiddleware,
- * } from '@abloatai/ablo/ai-sdk';
+ * import { tool, streamText } from 'ai';
+ * import { z } from 'zod';
  *
- * const target = { entityType: 'SlideDeck', entityId: 'deck-abc' };
+ * const renameTask = tool({
+ *   description: 'Rename a task.',
+ *   inputSchema: z.object({
+ *     id: z.string().describe('Task id'),
+ *     title: z.string().describe('New task title'),
+ *     description: z
+ *       .string()
+ *       .describe('Why this rename is being made'),
+ *   }),
+ *   execute: async ({ id, title, description }) => {
+ *     await ablo.tasks.update({
+ *       id,
+ *       data: { title },
+ *       wait: 'confirmed',
+ *       claim: {
+ *         field: 'title',
+ *         action: 'renaming',
+ *         description,
+ *       },
+ *     });
  *
- * const wrappedModel = wrapLanguageModel({
- *   model: anthropic('claude-opus-4-7'),
- *   middleware: [
- *     coordinationContextMiddleware({ agent, target }),
- *     intentBroadcastMiddleware({ agent, target }),
- *   ],
+ *     return { id, title };
+ *   },
  * });
  *
- * // Consumer keeps full control over messages, tools, system prompt:
- * const result = streamText({
- *   model: wrappedModel,
- *   messages: [...],
- *   tools: { ... },
- *   system: '...',
+ * await streamText({
+ *   model,
+ *   messages,
+ *   tools: { renameTask },
  * });
  * ```
  *
- * Or use the convenience composition for the common case:
+ * That is the common case. A claim passed directly to `update` is acquired,
+ * attached to the write, and released by the SDK.
  *
- * ```ts
- * import { wrapWithMultiplayer } from '@abloatai/ablo/ai-sdk';
+ * For multi-step tools, take one handle and release it when the tool is done:
  *
- * const wrappedModel = wrapWithMultiplayer({
- *   model: anthropic('claude-opus-4-7'),
- *   agent,
- *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
+ * ```ts
+ * const claim = await ablo.tasks.claim({
+ *   id,
+ *   action: 'rewriting',
+ *   description: 'Rewriting the task brief before updating follow-up fields.',
+ *   ttl: '2m',
  * });
+ *
+ * try {
+ *   await ablo.tasks.update({ id, data: { title }, claim });
+ *   await ablo.tasks.update({ id, data: { description: brief }, claim });
+ * } finally {
+ *   await claim.release();
+ * }
  * ```
  *
- * 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.
+ * `claim.state`, `claim.queue`, and `claim.reorder` are coordination reads and
+ * scheduler controls. They are useful for UI or operators, but normal AI tools
+ * should start with `update({ id, data, claim })` or a manual claim handle.
+ *
+ * `wrapWithMultiplayer` is optional. Use it when the whole model call is scoped
+ * to one entity before any tool is chosen; tool implementations stay exactly
+ * the same.
  */
 export { intentBroadcastMiddleware, } from './intent-broadcast.js';
 export { coordinationContextMiddleware, } from './coordination-context.js';

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

@@ -62,6 +62,11 @@ export interface IntentBroadcastMiddlewareOptions<R extends SchemaRecord = Schem
      * `'edit'`, `'read'`, `'review'`, `'generate'`. Default `'edit'`.
      */
     readonly action?: string;
+    /**
+     * Peer-visible explanation of the specific work this model call is about to
+     * perform. Surfaces to other agents through `ActiveIntent.description`.
+     */
+    readonly description?: string;
 }
 /**
  * Build the middleware. When `agent` or `target` is null, returns a

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

@@ -30,16 +30,23 @@
 export function intentBroadcastMiddleware(options) {
     const { agent, target } = options;
     const action = options.action ?? 'edit';
-    const openClaim = () => agent && target
-        ? agent.intents.claim({
+    const description = options.description;
+    const openClaim = () => {
+        if (!agent || !target)
+            return null;
+        return 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;
+        }, {
+            reason: action,
+            description,
+            ttl: target.estimatedMs ?? 60_000,
+        });
+    };
     return {
         specificationVersion: 'v3',
         // The AI SDK's middleware contract passes a no-arg `doStream` /

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

@@ -1,23 +1,21 @@
 /**
- * Convenience composition for the common case — wraps a language
- * model with both multiplayer middlewares (intent broadcast +
- * coordination context) in the right order.
+ * Optional model wrapper for entity-scoped turns.
  *
- * 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.
+ * Tool implementations do not change. Keep tools as normal AI SDK tools; use
+ * `ablo.<model>.update({ id, data, claim })` inside `execute`. This wrapper is
+ * only for the surrounding model call, when the UI already knows "this turn is
+ * about deck_abc" before the model chooses a tool.
  *
- * 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.).
+ * It declares one realtime claim while the model is generating and injects a
+ * short note if someone else is already working on the same target.
  *
  * ```ts
  * const wrapped = wrapWithMultiplayer({
  *   model: anthropic('claude-opus-4-7'),
  *   agent,
  *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
+ *   action: 'renaming',
+ *   description: 'Renaming the deck title to match the project brief.',
  * });
  *
  * const result = streamText({
@@ -46,6 +44,11 @@ export interface WrapWithMultiplayerOptions {
      * Convention: `'edit'`, `'read'`, `'review'`, `'generate'`.
      */
     readonly action?: string;
+    /**
+     * Peer-visible explanation of the specific work this model call is about to
+     * perform. Other agents receive it in their coordination context.
+     */
+    readonly description?: string;
     /**
      * Optional intentIds to exclude from the coordination-context
      * read — typically the caller's own claim if they're composing

package/dist/ai-sdk/wrap.js

@@ -1,23 +1,21 @@
 /**
- * Convenience composition for the common case — wraps a language
- * model with both multiplayer middlewares (intent broadcast +
- * coordination context) in the right order.
+ * Optional model wrapper for entity-scoped turns.
  *
- * 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.
+ * Tool implementations do not change. Keep tools as normal AI SDK tools; use
+ * `ablo.<model>.update({ id, data, claim })` inside `execute`. This wrapper is
+ * only for the surrounding model call, when the UI already knows "this turn is
+ * about deck_abc" before the model chooses a tool.
  *
- * 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.).
+ * It declares one realtime claim while the model is generating and injects a
+ * short note if someone else is already working on the same target.
  *
  * ```ts
  * const wrapped = wrapWithMultiplayer({
  *   model: anthropic('claude-opus-4-7'),
  *   agent,
  *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
+ *   action: 'renaming',
+ *   description: 'Renaming the deck title to match the project brief.',
  * });
  *
  * const result = streamText({
@@ -33,12 +31,12 @@ 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;
+    const { model, agent, target, action, description, excludeIntentIds, extraMiddleware } = options;
     return wrapLanguageModel({
         model,
         middleware: [
             coordinationContextMiddleware({ agent, target, excludeIntentIds }),
-            intentBroadcastMiddleware({ agent, target, action }),
+            intentBroadcastMiddleware({ agent, target, action, description }),
             ...(extraMiddleware ?? []),
         ],
     });

package/dist/auth/credentialSource.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Single mutable source for the SDK's active bearer credential.
+ *
+ * Every transport should read from this object at request/connect time:
+ * bootstrap HTTP, lazy query HTTP, identity/probe HTTP, and WebSocket URL
+ * auth. Token refresh writes here once; consumers observe the new value
+ * through their getter without being manually patched one by one.
+ */
+/**
+ * WebSocket subprotocols used to carry the bearer credential OUT of the URL.
+ *
+ * Browsers cannot set an `Authorization` header on a WebSocket, so the SDK
+ * offers the token as a `Sec-WebSocket-Protocol` value — `ablo.bearer.<token>` —
+ * alongside the real `ablo.sync.v1` protocol the server selects. This keeps the
+ * credential out of the query string, which ALB access logs, proxies, and
+ * browser history capture. The server reads the token from the subprotocol and
+ * echoes back ONLY `ablo.sync.v1`, never the token-bearing value. Shared with
+ * the sync-server so client and server can never drift on the wire format.
+ */
+export declare const WS_BEARER_SUBPROTOCOL_PREFIX = "ablo.bearer.";
+export declare const WS_SYNC_SUBPROTOCOL = "ablo.sync.v1";
+export interface AuthCredentialSource {
+    getAuthToken(): string | null;
+    setAuthToken(token: string | null | undefined): void;
+    authorizationHeader(): string | undefined;
+    withAuthHeaders(headers?: Record<string, string>): Record<string, string>;
+    applyAuthQueryParam(params: URLSearchParams, paramName?: string): void;
+}
+export type AuthTokenGetter = () => string | null | undefined;
+export declare function createAuthCredentialSource(initialToken?: string | null): AuthCredentialSource;
+export declare function resolveAuthToken(getAuthToken?: AuthTokenGetter, fallbackToken?: string | null): string | undefined;
+export declare function authorizationHeaderForToken(token: string | null | undefined): string | undefined;
+export declare function withAuthHeaders(getAuthToken: AuthTokenGetter | undefined, headers?: Record<string, string>, fallbackToken?: string | null): Record<string, string>;
+export declare function applyAuthToQueryParams(params: URLSearchParams, getAuthToken: AuthTokenGetter | undefined, paramName?: string, fallbackToken?: string | null): void;

package/dist/auth/credentialSource.js

@@ -0,0 +1,63 @@
+/**
+ * Single mutable source for the SDK's active bearer credential.
+ *
+ * Every transport should read from this object at request/connect time:
+ * bootstrap HTTP, lazy query HTTP, identity/probe HTTP, and WebSocket URL
+ * auth. Token refresh writes here once; consumers observe the new value
+ * through their getter without being manually patched one by one.
+ */
+/**
+ * WebSocket subprotocols used to carry the bearer credential OUT of the URL.
+ *
+ * Browsers cannot set an `Authorization` header on a WebSocket, so the SDK
+ * offers the token as a `Sec-WebSocket-Protocol` value — `ablo.bearer.<token>` —
+ * alongside the real `ablo.sync.v1` protocol the server selects. This keeps the
+ * credential out of the query string, which ALB access logs, proxies, and
+ * browser history capture. The server reads the token from the subprotocol and
+ * echoes back ONLY `ablo.sync.v1`, never the token-bearing value. Shared with
+ * the sync-server so client and server can never drift on the wire format.
+ */
+export const WS_BEARER_SUBPROTOCOL_PREFIX = 'ablo.bearer.';
+export const WS_SYNC_SUBPROTOCOL = 'ablo.sync.v1';
+export function createAuthCredentialSource(initialToken) {
+    let authToken = normalizeToken(initialToken);
+    return {
+        getAuthToken: () => authToken,
+        setAuthToken(token) {
+            authToken = normalizeToken(token);
+        },
+        authorizationHeader() {
+            return authorizationHeaderForToken(authToken);
+        },
+        withAuthHeaders(headers = {}) {
+            const authorization = authorizationHeaderForToken(authToken);
+            return authorization ? { ...headers, Authorization: authorization } : { ...headers };
+        },
+        applyAuthQueryParam(params, paramName = 'authorization') {
+            applyAuthToQueryParams(params, () => authToken, paramName);
+        },
+    };
+}
+export function resolveAuthToken(getAuthToken, fallbackToken) {
+    return normalizeToken(getAuthToken?.() ?? fallbackToken) ?? undefined;
+}
+export function authorizationHeaderForToken(token) {
+    const normalized = normalizeToken(token);
+    return normalized ? `Bearer ${normalized}` : undefined;
+}
+export function withAuthHeaders(getAuthToken, headers = {}, fallbackToken) {
+    const authorization = authorizationHeaderForToken(resolveAuthToken(getAuthToken, fallbackToken));
+    return authorization ? { ...headers, Authorization: authorization } : { ...headers };
+}
+export function applyAuthToQueryParams(params, getAuthToken, paramName = 'authorization', fallbackToken) {
+    const authorization = authorizationHeaderForToken(resolveAuthToken(getAuthToken, fallbackToken));
+    if (authorization) {
+        params.set(paramName, authorization);
+    }
+}
+function normalizeToken(token) {
+    if (!token)
+        return null;
+    const trimmed = token.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}

package/dist/auth/index.d.ts

@@ -11,21 +11,8 @@
  * 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>;
-}
+import { type CapabilityExchangeResponse, type IdentityResolveResponse } from './schemas.js';
+export type { CapabilityExchangeResponse, IdentityResolveResponse } from './schemas.js';
 export interface ExchangeApiKeyRequest {
     readonly apiKey: string;
     readonly baseUrl: string;
@@ -41,13 +28,6 @@ export interface ExchangeApiKeyRequest {
     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;

package/dist/auth/index.js

@@ -11,7 +11,8 @@
  * SDKs hide their internal auth-handshake — the apiKey is the only
  * credential the consumer touches.
  */
-import { AbloAuthenticationError } from '../errors.js';
+import { parseCapabilityExchangeResponse, parseIdentityResolveResponse, } from './schemas.js';
+import { AbloAuthenticationError, hasWireCode, translateHttpError } from '../errors.js';
 export async function exchangeApiKey(options) {
     if (!options.apiKey) {
         throw new AbloAuthenticationError('apiKey is required for capability exchange', { code: 'apikey_missing' });
@@ -59,33 +60,18 @@ export async function exchangeApiKey(options) {
         catch {
             // ignore — server returned non-JSON error
         }
-        const errBody = body;
-        throw new AbloAuthenticationError(`apiKey exchange rejected (${response.status}): ${errBody?.reason ?? response.statusText}`, {
-            code: errBody?.error ?? 'exchange_failed',
-            httpStatus: response.status,
-        });
-    }
-    const raw = (await response.json());
-    if (!isCapabilityExchangeResponse(raw)) {
-        throw new AbloAuthenticationError('apiKey exchange response was malformed — missing required fields', { code: 'exchange_malformed_response' });
-    }
-    return raw;
-}
-function isCapabilityExchangeResponse(raw) {
-    if (!raw || typeof raw !== 'object')
-        return false;
-    const o = raw;
-    if (typeof o.token !== 'string')
-        return false;
-    if (typeof o.expiresAt !== 'string')
-        return false;
-    if (typeof o.organizationId !== 'string')
-        return false;
-    if (typeof o.scope !== 'object' || o.scope === null)
-        return false;
-    if (typeof o.userMeta !== 'object' || o.userMeta === null)
-        return false;
-    return true;
+        // Route through the canonical wire-error translator so the server's
+        // envelope (`code` + `message` + `doc_url`) propagates verbatim and maps to
+        // the right AbloError subclass — instead of the legacy `error`/`reason`
+        // shape this used to read (which the server no longer emits, collapsing
+        // every failure to a generic code with an empty message). Fall back to
+        // `exchange_failed` only when the body carried no recognizable code.
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        throw hasWireCode(body)
+            ? translateHttpError(response.status, body, requestId)
+            : new AbloAuthenticationError(`apiKey exchange rejected (${response.status})`, { code: 'exchange_failed', httpStatus: response.status });
+    }
+    return parseCapabilityExchangeResponse(await response.json());
 }
 /**
  * Resolve the caller's Ablo identity from the authenticated request
@@ -112,7 +98,6 @@ export async function resolveIdentity(options) {
         response = await fetcher(url, {
             method: 'GET',
             headers,
-            credentials: 'include',
             signal: controller.signal,
         });
     }
@@ -130,13 +115,18 @@ export async function resolveIdentity(options) {
         catch {
             // ignore non-JSON auth errors
         }
-        const errBody = body;
-        throw new AbloAuthenticationError(`identity resolve rejected (${response.status}): ${errBody?.reason ?? response.statusText}`, {
-            code: errBody?.error ?? 'identity_resolve_failed',
-            httpStatus: response.status,
-        });
-    }
-    return (await response.json());
+        // Canonical envelope translation (see `exchangeApiKey` above). This is what
+        // surfaces the sync-server's precise auth diagnosis — e.g.
+        // `jwt_issuer_untrusted` with its full message — to the SDK consumer,
+        // instead of collapsing every 401 to `identity_resolve_failed` with an
+        // empty reason because the old parser looked for `error`/`reason` keys the
+        // server doesn't emit.
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        throw hasWireCode(body)
+            ? translateHttpError(response.status, body, requestId)
+            : new AbloAuthenticationError(`identity resolve rejected (${response.status})`, { code: 'identity_resolve_failed', httpStatus: response.status });
+    }
+    return parseIdentityResolveResponse(await response.json());
 }
 const DEFAULT_BUFFER_FLOOR_MS = 60_000;
 const DEFAULT_BUFFER_RATIO = 0.1;

package/dist/auth/schemas.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+export declare const AuthTokenSchema: z.ZodString;
+export declare const CapabilityExchangeResponseSchema: z.ZodObject<{
+    capabilityId: z.ZodString;
+    token: z.ZodString;
+    expiresAt: z.ZodString;
+    organizationId: z.ZodString;
+    scope: z.ZodObject<{
+        organizationId: z.ZodString;
+        syncGroups: z.ZodArray<z.ZodString>;
+        operations: z.ZodArray<z.ZodString>;
+        participantKind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        participantId: z.ZodString;
+    }, z.core.$loose>;
+    userMeta: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$loose>;
+export type CapabilityExchangeResponse = z.infer<typeof CapabilityExchangeResponseSchema>;
+export declare const IdentityResolveResponseSchema: z.ZodObject<{
+    participantKind: z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>;
+    participantId: z.ZodString;
+    accountScope: z.ZodString;
+    syncGroups: z.ZodArray<z.ZodString>;
+    userMeta: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$loose>;
+export type IdentityResolveResponse = z.infer<typeof IdentityResolveResponseSchema>;
+export declare function parseCapabilityExchangeResponse(raw: unknown): CapabilityExchangeResponse;
+export declare function parseIdentityResolveResponse(raw: unknown): IdentityResolveResponse;