@abloatai/ablo 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 0.19.0
+
+### Minor Changes
+
+- **Claim observability — a `ClaimLog` you can print or assert on.** A new
+  `observability` provider hook lets you tap every claim event and stale-write
+  collision the client sees. Hand `new ClaimLog()` to `Ablo({ observability })`
+  and it collects an ordered, readable log — `formatClaim` / `formatConflict`
+  render one line per event, and `collisions()` returns the conflicts for eval
+  assertions. New exports: `ClaimLog`, `formatClaim`, `formatConflict`,
+  `noopObservability`, and the types `ClaimLogEntry`, `ClaimEvent`,
+  `ConflictEvent`, `SyncObservabilityProvider`. Spread `noopObservability` to
+  override only the hooks you care about.
+
+  **AWS-shaped CLI credential store + `ablo config`.** Local CLI state is now split
+  into two files, matching `~/.aws/config` vs `~/.aws/credentials`: `config.json`
+  holds non-secret settings (active environment + active project) and is safe to
+  print or let an agent read; `credentials.json` holds the keys (0600, never
+  printed), keyed by project profile then environment. Per-project profiles follow
+  Stripe's model — `ablo projects use <slug>` selects the active profile, and a
+  key's project is fixed at mint so selecting a project never re-scopes an existing
+  key. `ablo status` now reports the resolved profile and environment.
+
+  **Schema JSON-column reconciliation.** `generateJsonColumnReconciliation` (new
+  export) emits the DDL to reconcile JSON-backed columns when adopting or evolving
+  an existing schema.
+
+  **Breaking (0.x):**
+  - The claim handle type `ClaimHandle` is renamed to **`Claim`**, and its
+    identifier field is `id` (was `claimId`). Update type imports and any code
+    reading `.claimId`.
+  - The ai-sdk `claimBroadcastMiddleware` (and `./ai-sdk/claim-broadcast`) is
+    removed — coordination broadcast is handled by `coordinationContextMiddleware`.
+    Import `ClaimTarget` from the package root or `@abloatai/ablo` ai-sdk's
+    `coordination-context` instead of `claim-broadcast`. The inline-claim option is
+    `reason` (not the pre-0.12 `action`); the ai-sdk docs are corrected to match.
+
+## 0.18.0
+
+### Minor Changes
+
+- **Client observability — `debug` / `logLevel`, off by default.** The SDK used to
+  emit a `debug` line per model and per property during schema registration (a
+  firehose). It now defaults to a quiet `warn` threshold and exposes two new
+  `Ablo()` options to opt back in:
+  - `logLevel: 'debug' | 'info' | 'warn' | 'error' | 'silent'` — `'info'` surfaces
+    coordination and connection events without the per-model registration noise;
+    `'debug'` is everything. Precedence: explicit `logLevel` → `debug: true` →
+    `ABLO_LOG_LEVEL` env → default `warn`. Supplying your own `logger` bypasses both.
+  - `debug: boolean` — shorthand for `logLevel: 'debug'`.
+
+  Coordination is now traceable at `info`: claims that are **rejected** or **lost**
+  (preempted/expired), and your position **advancing in a claim queue**, each log
+  once per change with a readable target (`documents:abc.title`) — quiet lowercase
+  lines, no shouty tags.
+
+  **New: canonical wire-egress contract export.** `errorEnvelope`, `statusForType`,
+  and the `ErrorEnvelope` type are now exported from the package root. Server
+  consumers (e.g. a self-hosted sync server) can assert against the one source of
+  truth for the error-envelope shape and the `AbloError`-subclass→HTTP-status
+  table instead of keeping a copy that silently drifts.
+
+  **Structured CLI error rendering.** CLI failures render as a titled block with a
+  reason code and per-code remediation (`--verbose` for the stack) instead of a
+  console wall-of-text; `AbloError.toString()` produces a leak-proof one-liner.
+
+  **`ABLO_API_KEY` resolution + sandbox key scopes.** The key is now resolved from
+  `.env.local` / `.env` (not just the process env), and sandbox keys are granted
+  `schema:push` by default so `ablo push` works out of the box in a fresh sandbox.
+
 ## 0.17.0
 
 ### Minor Changes

package/dist/BaseSyncedStore.d.ts

@@ -505,10 +505,11 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      *   1. REACTIVE — register `getToken` as the re-mint hook the FSM calls when a
      *      probe finds the key stale (`credential_stale`) or on a nudge.
      *   2. PROACTIVE — keep the short-lived key fresh ahead of trouble: a refresh
-     *      timer inside the TTL, plus re-mint on OS wake / network-online / tab
-     *      focus. Browser-only triggers are env-gated, so Node/agent hosts get
-     *      only the timer (a no-op there — agents use a static `apiKey`, no
-     *      resolver, so this is never called for them).
+     *      timer inside the TTL, plus re-mint on OS wake. The ENTIRE proactive
+     *      block is browser-gated (`typeof window`): server/SSR has no socket to
+     *      keep warm and the resolver is browser-oriented, so arming it in Node
+     *      would fire a relative-URL fetch and throw. (Agents pass a static
+     *      `apiKey` with no resolver, so this method is never called for them.)
      *
      * Config-driven and invisible, like Supabase's `autoRefreshToken` — consumers
      * never call a refresh method. Idempotent (a second call replaces the first);

package/dist/BaseSyncedStore.js

@@ -739,9 +739,21 @@ export class BaseSyncedStore {
                 // A throw = transient (offline / mint endpoint unreachable / 5xx). The
                 // login may be perfectly valid; never sign out for this — back off and
                 // retry. Mirrors the `getToken` throw-vs-null contract end-to-end.
-                getContext().logger.warn('[BaseSyncedStore] Access-credential re-mint failed (transient)', {
-                    error: error?.message,
-                });
+                const message = error?.message ?? String(error);
+                // A relative-URL resolver invoked server-side (Node fetch has no origin
+                // to resolve against) emits the opaque "Failed to parse URL" / "Only
+                // absolute URLs are supported". Translate it into something actionable
+                // instead of a mystery transient blip — the proactive refresh is now
+                // browser-only, so hitting this means the resolver fired from SSR/RSC or
+                // a server route.
+                if (typeof window === 'undefined' && /parse URL|absolute URLs?/i.test(message)) {
+                    getContext().logger.warn('credential resolver ran on the server with a relative URL — Node fetch needs an absolute URL. ' +
+                        'Refresh the Ablo client in the browser, or build an absolute URL server-side ' +
+                        "(e.g. new URL('/api/ablo-session', process.env.NEXT_PUBLIC_APP_URL)).", { error: message });
+                }
+                else {
+                    getContext().logger.warn('access-credential re-mint failed (transient)', { error: message });
+                }
                 return 'network_error';
             }
         })();
@@ -769,10 +781,11 @@ export class BaseSyncedStore {
      *   1. REACTIVE — register `getToken` as the re-mint hook the FSM calls when a
      *      probe finds the key stale (`credential_stale`) or on a nudge.
      *   2. PROACTIVE — keep the short-lived key fresh ahead of trouble: a refresh
-     *      timer inside the TTL, plus re-mint on OS wake / network-online / tab
-     *      focus. Browser-only triggers are env-gated, so Node/agent hosts get
-     *      only the timer (a no-op there — agents use a static `apiKey`, no
-     *      resolver, so this is never called for them).
+     *      timer inside the TTL, plus re-mint on OS wake. The ENTIRE proactive
+     *      block is browser-gated (`typeof window`): server/SSR has no socket to
+     *      keep warm and the resolver is browser-oriented, so arming it in Node
+     *      would fire a relative-URL fetch and throw. (Agents pass a static
+     *      `apiKey` with no resolver, so this method is never called for them.)
      *
      * Config-driven and invisible, like Supabase's `autoRefreshToken` — consumers
      * never call a refresh method. Idempotent (a second call replaces the first);
@@ -807,14 +820,25 @@ export class BaseSyncedStore {
             // 'network_error' → transient (offline / mint hiccup); the next timer tick
             // or the FSM's own probe retries. Never sign out for it.
         };
-        // Comfortably inside the 15m `ek_` TTL; a missed (background-throttled) tick
-        // is recovered by the next, or by the reactive probe. The timer is the sole
-        // proactive PRE-ROLL — it keeps the key warm ahead of expiry even while the
-        // socket sits healthy-`connected` (a state the FSM never probes unprompted).
-        const REFRESH_INTERVAL_MS = 10 * 60 * 1000;
-        const timer = setInterval(() => void refresh(), REFRESH_INTERVAL_MS);
-        const teardowns = [() => clearInterval(timer)];
+        const teardowns = [];
+        // The ENTIRE proactive pre-roll is BROWSER-ONLY. On the server (Next.js
+        // SSR/RSC evaluating the `providers` module) there is no live socket to keep
+        // warm AND the scaffolded credential resolver is browser-oriented (a
+        // relative-URL `fetch('/api/ablo-session')`). Arming the timer server-side
+        // fires that resolver in Node, where fetch has no origin to resolve a
+        // relative URL against → "Failed to parse URL" on every tick. Browser-only
+        // refresh is the unanimous vendor model (Supabase `autoRefreshToken: isBrowser()`,
+        // Clerk/Ably/Stripe refresh client-side). The reactive re-mint hook
+        // (`setCredentialRefresher` above) stays UNCONDITIONAL: it only fires on a
+        // real connection probe, which can't happen during a bare SSR module eval.
         if (typeof window !== 'undefined') {
+            // Comfortably inside the 15m `ek_` TTL; a missed (background-throttled)
+            // tick is recovered by the next, or by the reactive probe. The timer is
+            // the sole proactive PRE-ROLL — it keeps the key warm ahead of expiry even
+            // while the socket sits healthy-`connected` (a state the FSM never probes).
+            const REFRESH_INTERVAL_MS = 10 * 60 * 1000;
+            const timer = setInterval(() => void refresh(), REFRESH_INTERVAL_MS);
+            teardowns.push(() => clearInterval(timer));
             // OS-wake (desktop only): the Electron shell bridges `powerMonitor`
             // 'resume' to this DOM event. This is the ONE event-trigger the lifecycle
             // still owns, because `visibilitychange` does NOT fire on wake-from-sleep

package/dist/NetworkMonitor.js

@@ -31,7 +31,9 @@ export class NetworkMonitor extends EventEmitter {
         const wasOnline = this.isOnline;
         this.isOnline = false;
         if (wasOnline) {
-            getContext().logger.warn('Network connection lost');
+            // Symmetric with 'Network connection restored' (info) — expected,
+            // transient connectivity state, not an actionable warning.
+            getContext().logger.info('Network connection lost');
             this.emit('offline');
         }
     };

package/dist/ObjectPool.d.ts

@@ -111,7 +111,20 @@ export declare class ObjectPool {
         __class?: string;
         modelName?: string;
         id?: string;
-    }, ModelClass?: new (data: Record<string, unknown>) => Model): Model | null;
+    }, ModelClass?: new (data: Record<string, unknown>) => Model, opts?: {
+        /**
+         * Throw (instead of warn + return null) when the wire names a model
+         * this client never registered. Passed by the developer-await read
+         * path (`HydrationCoordinator`'s network leg) so a schema collision
+         * — the org's pushed schema names `Document` but this client only
+         * registered `documents` — surfaces AT the row that failed, with the
+         * known-model list and `ablo status` pointer, instead of bubbling up
+         * three layers later as a misleading `entity_not_found`. Left off
+         * (default) for the continuous delta loop and IDB-cache hydration,
+         * where a single unknown typename must not wedge the whole batch.
+         */
+        strict?: boolean;
+    }): Model | null;
     /**
      * Clear the object pool
      * @param options.preserveObserved - If true, keep models that are being observed by React

package/dist/ObjectPool.js

@@ -603,7 +603,7 @@ export class ObjectPool {
     create(typename, data) {
         return this.createFromData({ ...data, __typename: typename });
     }
-    createFromData(data, ModelClass) {
+    createFromData(data, ModelClass, opts) {
         // Support multiple model identifier fields for backwards compatibility
         const modelName = data.__typename ?? data.__class ?? data.modelName ?? 'Unknown';
         const Constructor = ModelClass || this.registry.getModelByName(modelName);
@@ -613,6 +613,13 @@ export class ObjectPool {
                 getContext().modelDebugLogger?.logError('Unknown', 'CREATE', 'No model identifier found', data);
                 return null;
             }
+            if (opts?.strict) {
+                const known = this.registry.getRegisteredModelNames();
+                throw new AbloValidationError(`Model "${modelName}" is not registered on this client` +
+                    (known.length ? ` (known: ${known.join(', ')})` : '') +
+                    `. The schema pushed to this org may differ from your local ` +
+                    `schema — run \`ablo status\` to compare.`, { code: 'model_not_registered' });
+            }
             getContext().logger.warn(`ObjectPool.createFromData: No constructor found for model "${modelName}"`, { data });
             getContext().modelDebugLogger?.logError(modelName, 'CREATE', `No constructor found for model "${modelName}"`, data);
             return null;

package/dist/SyncClient.js

@@ -161,8 +161,14 @@ export class SyncClient extends EventEmitter {
             // (e.g. `AbloValidationError` with `code: 'schema_...'`,
             // `AbloServerError` with `httpStatus: 500`). Falling back to
             // generic message lets us still see unstructured errors.
+            // Mechanic-level breadcrumb only. The authoritative, user-facing
+            // reason is logged once at `warn` by `TransactionQueue.handleFailure`
+            // (`Permanent error - rolling back`). Logging the same typed cause
+            // again here at `warn` is what produced three identical dumps per
+            // rejected write — keep it at `debug` so the rollback mechanics are
+            // available when debugging but don't double the console noise.
             const abloErr = error instanceof AbloError ? error : undefined;
-            getContext().logger.warn('[SyncClient.rollback]', {
+            getContext().logger.debug('[SyncClient.rollback]', {
                 txType: transaction.type,
                 modelName: transaction.modelName,
                 modelId: transaction.modelId.slice(0, 12),

package/dist/SyncEngineContext.js

@@ -28,6 +28,8 @@ export const noopObservability = {
     captureWebSocketError() { },
     captureOfflineFlushFailure() { },
     captureSelfHealing() { },
+    captureClaim() { },
+    captureConflict() { },
     captureCommitZeroSyncId() { },
     startSpan(_name, _op, fn, _attributes) {
         return fn();

package/dist/ai-sdk/coordination-context.d.ts

@@ -23,7 +23,8 @@
 import type { LanguageModelV3Middleware } from '@ai-sdk/provider';
 import type { Ablo } from '../client/Ablo.js';
 import type { SchemaRecord } from '../schema/schema.js';
-import type { ClaimTarget } from './claim-broadcast.js';
+import type { ClaimTarget } from '../types/streams.js';
+export type { ClaimTarget };
 export interface CoordinationContextMiddlewareOptions<R extends SchemaRecord = SchemaRecord> {
     readonly agent: Ablo<R> | null;
     readonly target: ClaimTarget | null;

package/dist/ai-sdk/coordination-context.js

@@ -38,8 +38,8 @@ export function coordinationContextMiddleware(options) {
                 return params;
             // Read peer claims on the same target. Synchronous lookup
             // against the engine's reactive claims.others array — no I/O.
-            const peerClaims = agent.claims.others.filter((claim) => claim.target.type === target.entityType &&
-                claim.target.id === target.entityId &&
+            const peerClaims = agent.claims.others.filter((claim) => claim.target.type === target.type &&
+                claim.target.id === target.id &&
                 targetsOverlap(claim.target, target) &&
                 !excludeClaimIds.has(claim.id));
             if (peerClaims.length === 0)
@@ -77,7 +77,7 @@ function targetsOverlap(claimTarget, target) {
  * "AI knows," not "AI gets a wall of text."
  */
 function formatCoordinationNote(claims, target) {
-    const entityLabel = target.entityType.toLowerCase();
+    const entityLabel = target.type.toLowerCase();
     if (claims.length === 1) {
         const c = claims[0];
         const details = c.description ? `Declared work: ${c.description}. ` : '';

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

@@ -27,7 +27,7 @@
  *       wait: 'confirmed',
  *       claim: {
  *         field: 'title',
- *         action: 'renaming',
+ *         reason: 'renaming',
  *         description,
  *       },
  *     });
@@ -51,7 +51,7 @@
  * ```ts
  * const claim = await ablo.tasks.claim({
  *   id,
- *   action: 'rewriting',
+ *   reason: 'rewriting',
  *   description: 'Rewriting the task brief before updating follow-up fields.',
  *   ttl: '2m',
  * });
@@ -72,6 +72,5 @@
  * to one entity before any tool is chosen; tool implementations stay exactly
  * the same.
  */
-export { claimBroadcastMiddleware, type ClaimTarget, type ClaimBroadcastMiddlewareOptions, } from './claim-broadcast.js';
-export { coordinationContextMiddleware, type CoordinationContextMiddlewareOptions, } from './coordination-context.js';
+export { coordinationContextMiddleware, type CoordinationContextMiddlewareOptions, type ClaimTarget, } from './coordination-context.js';
 export { wrapWithMultiplayer, type WrapWithMultiplayerOptions } from './wrap.js';

package/dist/ai-sdk/index.js

@@ -27,7 +27,7 @@
  *       wait: 'confirmed',
  *       claim: {
  *         field: 'title',
- *         action: 'renaming',
+ *         reason: 'renaming',
  *         description,
  *       },
  *     });
@@ -51,7 +51,7 @@
  * ```ts
  * const claim = await ablo.tasks.claim({
  *   id,
- *   action: 'rewriting',
+ *   reason: 'rewriting',
  *   description: 'Rewriting the task brief before updating follow-up fields.',
  *   ttl: '2m',
  * });
@@ -72,6 +72,5 @@
  * to one entity before any tool is chosen; tool implementations stay exactly
  * the same.
  */
-export { claimBroadcastMiddleware, } from './claim-broadcast.js';
 export { coordinationContextMiddleware, } from './coordination-context.js';
 export { wrapWithMultiplayer } from './wrap.js';

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

@@ -14,8 +14,6 @@
  *   model: anthropic('claude-opus-4-7'),
  *   agent,
  *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
- *   reason: 'renaming',
- *   description: 'Renaming the deck title to match the project brief.',
  * });
  *
  * const result = streamText({
@@ -31,25 +29,22 @@ import { wrapLanguageModel } from 'ai';
 import type { LanguageModelV3, LanguageModelV3Middleware } from '@ai-sdk/provider';
 import type { Ablo } from '../client/Ablo.js';
 import type { SchemaRecord } from '../schema/schema.js';
-import { type ClaimTarget } from './claim-broadcast.js';
-export interface WrapWithMultiplayerOptions {
+import { type ClaimTarget } from './coordination-context.js';
+export interface WrapWithMultiplayerOptions<R extends SchemaRecord = SchemaRecord> {
     /** The base language model to wrap. Consumer brings their own. */
     readonly model: LanguageModelV3;
-    /** Connected SyncAgent. Null = pass-through wrap (no broadcast, no read). */
-    readonly agent: Ablo<SchemaRecord> | null;
-    /** Target entity. Null = pass-through wrap. */
-    readonly target: ClaimTarget | null;
-    /**
-     * Optional human-readable phase for the broadcast. Default `'edit'`.
-     * Convention: `'edit'`, `'read'`, `'review'`, `'generate'`. The same
-     * `reason` field used on every claim surface.
-     */
-    readonly reason?: string;
     /**
-     * Peer-visible explanation of the specific work this model call is about to
-     * perform. Other agents receive it in their coordination context.
+     * Connected Ablo. Null = pass-through wrap (no broadcast, no read).
+     *
+     * Generic over the schema record (like the two middlewares it composes) so a
+     * caller passing a typed `Ablo<typeof schema>` doesn't have to cast: `Ablo<S>`
+     * and `Ablo<SchemaRecord>` aren't structurally assignable (the widened version
+     * collapses model proxies to an index signature that clashes with the named
+     * methods `ready`/`dispose`/…).
      */
-    readonly description?: string;
+    readonly agent: Ablo<R> | null;
+    /** Target entity. Null = pass-through wrap. */
+    readonly target: ClaimTarget | null;
     /**
      * Optional claimIds to exclude from the coordination-context
      * read — typically the caller's own claim if they're composing
@@ -68,4 +63,4 @@ export interface WrapWithMultiplayerOptions {
      */
     readonly extraMiddleware?: readonly LanguageModelV3Middleware[];
 }
-export declare function wrapWithMultiplayer(options: WrapWithMultiplayerOptions): ReturnType<typeof wrapLanguageModel>;
+export declare function wrapWithMultiplayer<R extends SchemaRecord = SchemaRecord>(options: WrapWithMultiplayerOptions<R>): ReturnType<typeof wrapLanguageModel>;

package/dist/ai-sdk/wrap.js

@@ -14,8 +14,6 @@
  *   model: anthropic('claude-opus-4-7'),
  *   agent,
  *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
- *   reason: 'renaming',
- *   description: 'Renaming the deck title to match the project brief.',
  * });
  *
  * const result = streamText({
@@ -28,15 +26,13 @@
  * ```
  */
 import { wrapLanguageModel } from 'ai';
-import { claimBroadcastMiddleware, } from './claim-broadcast.js';
-import { coordinationContextMiddleware } from './coordination-context.js';
+import { coordinationContextMiddleware, } from './coordination-context.js';
 export function wrapWithMultiplayer(options) {
-    const { model, agent, target, reason, description, excludeClaimIds, extraMiddleware } = options;
+    const { model, agent, target, excludeClaimIds, extraMiddleware } = options;
     return wrapLanguageModel({
         model,
         middleware: [
             coordinationContextMiddleware({ agent, target, excludeClaimIds }),
-            claimBroadcastMiddleware({ agent, target, reason, description }),
             ...(extraMiddleware ?? []),
         ],
     });