@xemahq/ui-kernel 0.2.0 → 0.3.0

package/dist/lib/biome-host/errors.d.ts

@@ -0,0 +1,2 @@
+export declare function getUserFacingErrorMessage(error: unknown, fallback?: string): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/biome-host/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/lib/biome-host/errors.ts"],"names":[],"mappings":"AA0MA,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,EACd,QAAQ,SAA4C,GACnD,MAAM,CAcR"}

package/dist/lib/biome-host/errors.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getUserFacingErrorMessage = getUserFacingErrorMessage;
+function collapseWhitespace(value) {
+    return value.split(/\s+/).join(' ').trim();
+}
+function getGenericErrorMessage(message, fallback) {
+    const normalized = collapseWhitespace(message);
+    if (/failed to fetch/i.test(normalized)) {
+        return 'Could not reach the service. Check your connection and try again.';
+    }
+    return normalized || fallback;
+}
+function normalizeValidationMessage(rawMessage) {
+    const parts = rawMessage
+        .split(',')
+        .map((part) => collapseWhitespace(part))
+        .filter(Boolean);
+    if (parts.length === 0) {
+        return 'Some required fields are missing or invalid. Please review your input and try again.';
+    }
+    const preview = parts.slice(0, 2).join('; ');
+    const suffix = parts.length > 2 ? '; and more.' : '.';
+    return `Some required fields are missing or invalid (${preview}${suffix})`;
+}
+function isApiClientErrorLike(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const record = error;
+    return (record['name'] === 'ApiClientError' &&
+        typeof record['statusCode'] === 'number' &&
+        typeof record['message'] === 'string');
+}
+function isOrvalClientErrorLike(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const record = error;
+    return (record['name'] === 'ClientError' &&
+        typeof record['status'] === 'number' &&
+        typeof record['message'] === 'string' &&
+        Object.hasOwn(record, 'body'));
+}
+function readStringList(value) {
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    if (value.some((entry) => typeof entry !== 'string')) {
+        return null;
+    }
+    return value;
+}
+function normalizeWorkflowWalletMissingMessage(envelope) {
+    if (envelope.code !== 'WORKFLOW_WALLET_NOT_FOUND') {
+        return null;
+    }
+    const missing = readStringList(envelope.details?.['missing']);
+    if (missing === null || missing.length === 0) {
+        return 'One or more required wallets are missing for this project.';
+    }
+    return `Missing wallet${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}. Add ${missing.length > 1 ? 'them' : 'it'} in Project Settings -> Wallets.`;
+}
+function getApiClientErrorMessage(error, fallback) {
+    if (error.statusCode === 0) {
+        return collapseWhitespace(error.message) || fallback;
+    }
+    if (error.statusCode === 400) {
+        const raw = collapseWhitespace(error.message);
+        if (raw.includes(' must ') || raw.includes('regular expression')) {
+            return normalizeValidationMessage(raw);
+        }
+        return raw || 'The request is invalid. Please check your input and try again.';
+    }
+    if (error.statusCode === 401) {
+        return 'Your session expired. Please sign in again.';
+    }
+    if (error.statusCode === 403) {
+        return 'You do not have permission to perform this action.';
+    }
+    if (error.statusCode === 404) {
+        return 'The requested resource was not found.';
+    }
+    if (error.statusCode >= 500) {
+        return 'The service is temporarily unavailable. Please try again in a moment.';
+    }
+    return collapseWhitespace(error.message) || fallback;
+}
+function getOrvalClientErrorMessage(error, fallback) {
+    if (error.status >= 500) {
+        return 'The service is temporarily unavailable. Please try again in a moment.';
+    }
+    if (error.status === 409) {
+        const body = error.body;
+        if (body && typeof body === 'object') {
+            const record = body;
+            if (record['error'] === 'session_busy') {
+                return 'Your last message is still running. Wait for the agent to finish, then try again.';
+            }
+        }
+    }
+    const body = error.body;
+    if (body && typeof body === 'object') {
+        const record = body;
+        const payload = (() => {
+            const message = record['message'];
+            if (message && typeof message === 'object') {
+                return message;
+            }
+            return {
+                code: typeof record['code'] === 'string' ? record['code'] : undefined,
+                message: typeof record['message'] === 'string' ? record['message'] : undefined,
+                details: record['details'] && typeof record['details'] === 'object'
+                    ? record['details']
+                    : undefined,
+            };
+        })();
+        const workflowWalletMessage = normalizeWorkflowWalletMissingMessage(payload);
+        if (workflowWalletMessage !== null) {
+            return workflowWalletMessage;
+        }
+        if (typeof payload.message === 'string' && payload.message.trim().length > 0) {
+            return collapseWhitespace(payload.message);
+        }
+        if (typeof record['message'] === 'string' && record['message'].trim().length > 0) {
+            return collapseWhitespace(record['message']);
+        }
+    }
+    return getGenericErrorMessage(error.message, fallback);
+}
+function getUserFacingErrorMessage(error, fallback = 'Something went wrong. Please try again.') {
+    if (typeof error === 'string') {
+        return collapseWhitespace(error) || fallback;
+    }
+    if (isApiClientErrorLike(error)) {
+        return getApiClientErrorMessage(error, fallback);
+    }
+    if (isOrvalClientErrorLike(error)) {
+        return getOrvalClientErrorMessage(error, fallback);
+    }
+    if (error instanceof Error) {
+        return getGenericErrorMessage(error.message, fallback);
+    }
+    return fallback;
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/biome-host/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/lib/biome-host/errors.ts"],"names":[],"mappings":"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"}

package/dist/lib/biome-host/host-bridge.d.ts

@@ -2,6 +2,7 @@ import type { QueryClient } from '@tanstack/react-query';
 import { type ReactNode } from 'react';
 import type { CapabilityPort } from '../capabilities';
 import type { SystemBus } from '../system-bus';
+import type { RealtimeSource } from './realtime-port';
 export interface HostBridgeNavigation {
     push(path: string): void;
     replace(path: string): void;
@@ -29,6 +30,9 @@ export interface HostBridgeToast {
 export interface HostBridgeRequestContext {
     readonly correlationId: string;
 }
+export interface HostBridgeErrors {
+    getUserFacingErrorMessage(error: unknown, fallback?: string): string;
+}
 export interface PageBackTarget {
     readonly to: string;
     readonly label?: string;
@@ -54,6 +58,8 @@ export interface HostBridge {
     readonly pageMeta: HostBridgePageMeta;
     readonly system: SystemBus;
     readonly capabilities: CapabilityPort;
+    readonly realtime?: RealtimeSource;
+    readonly errors?: HostBridgeErrors;
 }
 export declare const HostBridgeContext: import("react").Context<HostBridge | null>;
 export declare function useHostBridge(): HostBridge;

package/dist/lib/biome-host/host-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-bridge.d.ts","sourceRoot":"","sources":["../../../src/lib/biome-host/host-bridge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"host-bridge.d.ts","sourceRoot":"","sources":["../../../src/lib/biome-host/host-bridge.ts"],"names":[],"mappings":"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"}

package/dist/lib/biome-host/host-bridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"host-bridge.js","sourceRoot":"","sources":["../../../src/lib/biome-host/host-bridge.ts"],"names":[],"mappings":";;;AAqNA,sCASC;AA5ND,iCAAkE;AA2MrD,QAAA,iBAAiB,GAAG,IAAA,qBAAa,EAAoB,IAAI,CAAC,CAAC;AACxE,yBAAiB,CAAC,WAAW,GAAG,mBAAmB,CAAC;AAOpD,SAAgB,aAAa;IAC3B,MAAM,MAAM,GAAG,IAAA,kBAAU,EAAC,yBAAiB,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,gFAAgF;YAC9E,0EAA0E,CAC7E,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"host-bridge.js","sourceRoot":"","sources":["../../../src/lib/biome-host/host-bridge.ts"],"names":[],"mappings":";;;AAiQA,sCASC;AAxQD,iCAAkE;AAuPrD,QAAA,iBAAiB,GAAG,IAAA,qBAAa,EAAoB,IAAI,CAAC,CAAC;AACxE,yBAAiB,CAAC,WAAW,GAAG,mBAAmB,CAAC;AAOpD,SAAgB,aAAa;IAC3B,MAAM,MAAM,GAAG,IAAA,kBAAU,EAAC,yBAAiB,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,gFAAgF;YAC9E,0EAA0E,CAC7E,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/lib/biome-host/index.d.ts

@@ -12,4 +12,8 @@ export * from './host-sources';
 export * from './nav';
 export * from './biome-mode';
 export * from './agent-validation';
+export * from './realtime-port';
+export * from './realtime-hooks';
+export * from './errors';
+export * from './response-envelope';
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/biome-host/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/biome-host/index.ts"],"names":[],"mappings":"AAcA,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,OAAO,CAAC;AACtB,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/biome-host/index.ts"],"names":[],"mappings":"AAcA,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,OAAO,CAAC;AACtB,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC"}

package/dist/lib/biome-host/index.js

@@ -28,4 +28,8 @@ __exportStar(require("./host-sources"), exports);
 __exportStar(require("./nav"), exports);
 __exportStar(require("./biome-mode"), exports);
 __exportStar(require("./agent-validation"), exports);
+__exportStar(require("./realtime-port"), exports);
+__exportStar(require("./realtime-hooks"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./response-envelope"), exports);
 //# sourceMappingURL=index.js.map

package/dist/lib/biome-host/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/biome-host/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAcA,mDAAiC;AACjC,gDAA8B;AAC9B,qDAAmC;AACnC,gDAA8B;AAC9B,uDAAqC;AACrC,mDAAiC;AACjC,8DAA4C;AAC5C,mDAAiC;AACjC,0DAAwC;AACxC,qDAAmC;AACnC,iDAA+B;AAC/B,wCAAsB;AACtB,+CAA6B;AAC7B,qDAAmC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/biome-host/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAcA,mDAAiC;AACjC,gDAA8B;AAC9B,qDAAmC;AACnC,gDAA8B;AAC9B,uDAAqC;AACrC,mDAAiC;AACjC,8DAA4C;AAC5C,mDAAiC;AACjC,0DAAwC;AACxC,qDAAmC;AACnC,iDAA+B;AAC/B,wCAAsB;AACtB,+CAA6B;AAC7B,qDAAmC;AACnC,kDAAgC;AAChC,mDAAiC;AACjC,2CAAyB;AACzB,sDAAoC"}

package/dist/lib/biome-host/realtime-hooks.d.ts

@@ -0,0 +1,5 @@
+import type { RealtimeCloudEvent, RealtimeConnectionState, RealtimeScope } from './realtime-port';
+export declare function useCloudEvent(eventType: string, handler: (event: RealtimeCloudEvent) => void): void;
+export declare function useRealtimeStatus(): RealtimeConnectionState;
+export declare function useEventScope(scope: RealtimeScope): void;
+//# sourceMappingURL=realtime-hooks.d.ts.map

package/dist/lib/biome-host/realtime-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-hooks.d.ts","sourceRoot":"","sources":["../../../src/lib/biome-host/realtime-hooks.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,kBAAkB,EAClB,uBAAuB,EACvB,aAAa,EAEd,MAAM,iBAAiB,CAAC;AAiCzB,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAC3C,IAAI,CAGN;AAGD,wBAAgB,iBAAiB,IAAI,uBAAuB,CAG3D;AAOD,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAGxD"}

package/dist/lib/biome-host/realtime-hooks.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCloudEvent = useCloudEvent;
+exports.useRealtimeStatus = useRealtimeStatus;
+exports.useEventScope = useEventScope;
+const host_bridge_1 = require("./host-bridge");
+function requireRealtime(realtime) {
+    if (!realtime) {
+        throw new Error('useCloudEvent/useRealtimeStatus/useEventScope require a realtime ' +
+            'transport, but the host has not wired `bridge.realtime`. The host ' +
+            'must provide a RealtimeSource (e.g. backed by @xemahq/realtime-client) ' +
+            'on the HostBridge to use kernel realtime hooks.');
+    }
+    return realtime;
+}
+function useCloudEvent(eventType, handler) {
+    const bridge = (0, host_bridge_1.useHostBridge)();
+    requireRealtime(bridge.realtime).useCloudEvent(eventType, handler);
+}
+function useRealtimeStatus() {
+    const bridge = (0, host_bridge_1.useHostBridge)();
+    return requireRealtime(bridge.realtime).useRealtimeStatus();
+}
+function useEventScope(scope) {
+    const bridge = (0, host_bridge_1.useHostBridge)();
+    requireRealtime(bridge.realtime).useEventScope(scope);
+}
+//# sourceMappingURL=realtime-hooks.js.map

package/dist/lib/biome-host/realtime-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-hooks.js","sourceRoot":"","sources":["../../../src/lib/biome-host/realtime-hooks.ts"],"names":[],"mappings":";;AAmDA,sCAMC;AAGD,8CAGC;AAOD,sCAGC;AA7DD,+CAA8C;AAc9C,SAAS,eAAe,CAAC,QAAoC;IAC3D,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,mEAAmE;YACjE,oEAAoE;YACpE,yEAAyE;YACzE,iDAAiD,CACpD,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAeD,SAAgB,aAAa,CAC3B,SAAiB,EACjB,OAA4C;IAE5C,MAAM,MAAM,GAAG,IAAA,2BAAa,GAAE,CAAC;IAC/B,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AACrE,CAAC;AAGD,SAAgB,iBAAiB;IAC/B,MAAM,MAAM,GAAG,IAAA,2BAAa,GAAE,CAAC;IAC/B,OAAO,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,iBAAiB,EAAE,CAAC;AAC9D,CAAC;AAOD,SAAgB,aAAa,CAAC,KAAoB;IAChD,MAAM,MAAM,GAAG,IAAA,2BAAa,GAAE,CAAC;IAC/B,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;AACxD,CAAC"}

package/dist/lib/biome-host/realtime-port.d.ts

@@ -0,0 +1,30 @@
+export interface RealtimeCloudEvent {
+    id?: string;
+    type: string;
+    source?: string;
+    subject?: string;
+    data?: unknown;
+    ehorgid: string;
+    ehprojectid?: string;
+    ehuserid?: string;
+    ehglobalseq?: string;
+    ehorgseq?: string;
+    ehprojectseq?: string;
+    ehsessionseq?: string;
+    __hint?: unknown;
+}
+export type RealtimeStatus = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'closed';
+export interface RealtimeConnectionState {
+    readonly status: RealtimeStatus;
+    readonly connectionId?: string;
+}
+export interface RealtimeScope {
+    readonly kind: 'project' | 'session';
+    readonly id: string;
+}
+export interface RealtimeSource {
+    useCloudEvent(eventType: string, handler: (event: RealtimeCloudEvent) => void): void;
+    useRealtimeStatus(): RealtimeConnectionState;
+    useEventScope(scope: RealtimeScope): void;
+}
+//# sourceMappingURL=realtime-port.d.ts.map

package/dist/lib/biome-host/realtime-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-port.d.ts","sourceRoot":"","sources":["../../../src/lib/biome-host/realtime-port.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,kBAAkB;IAEjC,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,IAAI,EAAE,MAAM,CAAC;IAEb,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf,OAAO,EAAE,MAAM,CAAC;IAEhB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAGD,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,YAAY,GACZ,WAAW,GACX,cAAc,GACd,QAAQ,CAAC;AAGb,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAOD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAWD,MAAM,WAAW,cAAc;IAO7B,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAAG,IAAI,CAAC;IAErF,iBAAiB,IAAI,uBAAuB,CAAC;IAM7C,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;CAC3C"}

package/dist/lib/biome-host/realtime-port.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=realtime-port.js.map

package/dist/lib/biome-host/realtime-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-port.js","sourceRoot":"","sources":["../../../src/lib/biome-host/realtime-port.ts"],"names":[],"mappings":""}

package/dist/lib/biome-host/response-envelope.d.ts

@@ -0,0 +1,3 @@
+export declare function unwrapList<T>(value: unknown): T[];
+export declare function unwrapData<T>(value: unknown): T;
+//# sourceMappingURL=response-envelope.d.ts.map

package/dist/lib/biome-host/response-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-envelope.d.ts","sourceRoot":"","sources":["../../../src/lib/biome-host/response-envelope.ts"],"names":[],"mappings":"AA+BA,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,EAAE,CAYjD;AAeD,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAU/C"}

package/dist/lib/biome-host/response-envelope.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrapList = unwrapList;
+exports.unwrapData = unwrapData;
+function unwrapList(value) {
+    if (Array.isArray(value)) {
+        return value;
+    }
+    if (value !== null &&
+        typeof value === 'object' &&
+        Array.isArray(value.data)) {
+        return value.data;
+    }
+    return [];
+}
+function unwrapData(value) {
+    if (value !== null &&
+        typeof value === 'object' &&
+        'data' in value &&
+        !('pagination' in value)) {
+        return value.data;
+    }
+    return value;
+}
+//# sourceMappingURL=response-envelope.js.map

package/dist/lib/biome-host/response-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-envelope.js","sourceRoot":"","sources":["../../../src/lib/biome-host/response-envelope.ts"],"names":[],"mappings":";;AA+BA,gCAYC;AAeD,gCAUC;AArCD,SAAgB,UAAU,CAAI,KAAc;IAC1C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAY,CAAC;IACtB,CAAC;IACD,IACE,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,CAAC,OAAO,CAAE,KAA4B,CAAC,IAAI,CAAC,EACjD,CAAC;QACD,OAAQ,KAAuB,CAAC,IAAI,CAAC;IACvC,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAeD,SAAgB,UAAU,CAAI,KAAc;IAC1C,IACE,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,MAAM,IAAK,KAAiC;QAC5C,CAAC,CAAC,YAAY,IAAK,KAAiC,CAAC,EACrD,CAAC;QACD,OAAQ,KAAqB,CAAC,IAAI,CAAC;IACrC,CAAC;IACD,OAAO,KAAU,CAAC;AACpB,CAAC"}

package/dist/ui/chrome/ErrorCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ErrorCard.d.ts","sourceRoot":"","sources":["../../../src/ui/chrome/ErrorCard.tsx"],"names":[],"mappings":"AAWA,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;AAYjF,UAAU,cAAc;IACtB,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAMrB,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,CAAC,OAAO,UAAU,SAAS,CAAC,EAChC,KAAK,EACL,KAA8B,EAC9B,OAAO,EACP,WAAgC,EAChC,eAA0D,GAC3D,EAAE,cAAc,+BAyBhB"}
+{"version":3,"file":"ErrorCard.d.ts","sourceRoot":"","sources":["../../../src/ui/chrome/ErrorCard.tsx"],"names":[],"mappings":"AAaA,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;AAKjF,UAAU,cAAc;IACtB,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAMrB,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,CAAC,OAAO,UAAU,SAAS,CAAC,EAChC,KAAK,EACL,KAA8B,EAC9B,OAAO,EACP,WAAgC,EAChC,eAA0D,GAC3D,EAAE,cAAc,+BAyBhB"}

package/dist/ui/chrome/ErrorCard.js

@@ -3,17 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = ErrorCard;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const lucide_react_1 = require("lucide-react");
+const errors_1 = require("../../lib/biome-host/errors");
 const button_1 = require("../primitives/button");
 const card_1 = require("../primitives/card");
-const defaultFormatError = (error, fallback) => {
-    if (typeof error === 'string') {
-        return error || fallback;
-    }
-    if (error instanceof Error && error.message) {
-        return error.message;
-    }
-    return fallback;
-};
+const defaultFormatError = (error, fallback) => (0, errors_1.getUserFacingErrorMessage)(error, fallback);
 function ErrorCard({ error, title = 'Something went wrong', onRetry, formatError = defaultFormatError, fallbackMessage = 'Unable to load this content right now.', }) {
     const message = formatError(error, fallbackMessage);
     return ((0, jsx_runtime_1.jsx)(card_1.Card, { className: "border-destructive/25 bg-destructive/[0.03] rounded-xl", children: (0, jsx_runtime_1.jsxs)(card_1.CardContent, { className: "flex flex-col items-center py-14 text-center", children: [(0, jsx_runtime_1.jsx)("div", { className: "h-14 w-14 rounded-2xl bg-destructive/10 flex items-center justify-center mb-4", children: (0, jsx_runtime_1.jsx)(lucide_react_1.AlertCircle, { className: "h-6 w-6 text-destructive" }) }), (0, jsx_runtime_1.jsx)("p", { className: "text-subtitle font-semibold text-ink", children: title }), (0, jsx_runtime_1.jsx)("p", { className: "text-body-1 text-ink-3 mt-2 max-w-md leading-relaxed", children: message }), onRetry && ((0, jsx_runtime_1.jsxs)(button_1.Button, { size: "sm", variant: "outline", onClick: onRetry, className: "mt-5 gap-2 h-10 border-destructive/20 text-destructive hover:bg-destructive/5", children: [(0, jsx_runtime_1.jsx)(lucide_react_1.RefreshCw, { className: "h-4 w-4" }), "Retry"] }))] }) }));

package/dist/ui/chrome/ErrorCard.js.map

@@ -1 +1 @@
-{"version":3,"file":"ErrorCard.js","sourceRoot":"","sources":["../../../src/ui/chrome/ErrorCard.tsx"],"names":[],"mappings":";;AAoCA,4BA+BC;;AAnED,+CAAsD;AAEtD,iDAA8C;AAC9C,6CAAuD;AAUvD,MAAM,kBAAkB,GAA0B,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;IACpE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,IAAI,QAAQ,CAAC;IAC3B,CAAC;IACD,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAC5C,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC;AAeF,SAAwB,SAAS,CAAC,EAChC,KAAK,EACL,KAAK,GAAG,sBAAsB,EAC9B,OAAO,EACP,WAAW,GAAG,kBAAkB,EAChC,eAAe,GAAG,wCAAwC,GAC3C;IACf,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;IAEpD,OAAO,CACL,uBAAC,WAAI,IAAC,SAAS,EAAC,wDAAwD,YACtE,wBAAC,kBAAW,IAAC,SAAS,EAAC,8CAA8C,aACnE,gCAAK,SAAS,EAAC,+EAA+E,YAC5F,uBAAC,0BAAW,IAAC,SAAS,EAAC,0BAA0B,GAAG,GAChD,EACN,8BAAG,SAAS,EAAC,sCAAsC,YAAE,KAAK,GAAK,EAC/D,8BAAG,SAAS,EAAC,sDAAsD,YAAE,OAAO,GAAK,EAChF,OAAO,IAAI,CACV,wBAAC,eAAM,IACL,IAAI,EAAC,IAAI,EACT,OAAO,EAAC,SAAS,EACjB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAC,+EAA+E,aAEzF,uBAAC,wBAAS,IAAC,SAAS,EAAC,SAAS,GAAG,aAE1B,CACV,IACW,GACT,CACR,CAAC;AACJ,CAAC"}
+{"version":3,"file":"ErrorCard.js","sourceRoot":"","sources":["../../../src/ui/chrome/ErrorCard.tsx"],"names":[],"mappings":";;AA+BA,4BA+BC;;AA9DD,+CAAsD;AAEtD,wDAAwE;AACxE,iDAA8C;AAC9C,6CAAuD;AAWvD,MAAM,kBAAkB,GAA0B,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,CACpE,IAAA,kCAAyB,EAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AAe7C,SAAwB,SAAS,CAAC,EAChC,KAAK,EACL,KAAK,GAAG,sBAAsB,EAC9B,OAAO,EACP,WAAW,GAAG,kBAAkB,EAChC,eAAe,GAAG,wCAAwC,GAC3C;IACf,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;IAEpD,OAAO,CACL,uBAAC,WAAI,IAAC,SAAS,EAAC,wDAAwD,YACtE,wBAAC,kBAAW,IAAC,SAAS,EAAC,8CAA8C,aACnE,gCAAK,SAAS,EAAC,+EAA+E,YAC5F,uBAAC,0BAAW,IAAC,SAAS,EAAC,0BAA0B,GAAG,GAChD,EACN,8BAAG,SAAS,EAAC,sCAAsC,YAAE,KAAK,GAAK,EAC/D,8BAAG,SAAS,EAAC,sDAAsD,YAAE,OAAO,GAAK,EAChF,OAAO,IAAI,CACV,wBAAC,eAAM,IACL,IAAI,EAAC,IAAI,EACT,OAAO,EAAC,SAAS,EACjB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAC,+EAA+E,aAEzF,uBAAC,wBAAS,IAAC,SAAS,EAAC,SAAS,GAAG,aAE1B,CACV,IACW,GACT,CACR,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/ui-kernel",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Host-framework-agnostic UI kernel for the Xema OS. Defines the SystemBus orchestration contract (capability.invoke, cross-biome intents, command palette, xema:// deeplinks, window manager) AND the biome-host contract surface (FrontendBiome/FrontendBiomeFactory, HostBridge, the singleton biomeRegistry, session contributions) that every frontend biome composes against. No Vite, Next.js, or React-Router — React itself IS allowed as the shared component model (the contracts traffic in ReactNode/ComponentType and a React context). Concrete host adapters (router/auth/toast wiring) live in separate packages that consume this kernel. The SystemBus is pure orchestration: it never authorizes, the backend capability-router enforces all policy.",
   "keywords": [
     "xema",

package/src/lib/biome-host/errors.ts

@@ -0,0 +1,220 @@
+/**
+ * Canonical user-facing error decoder — ONE implementation biomes, the host
+ * shell, and the kernel's {@link ErrorCard} default all share.
+ *
+ * Biomes were each re-implementing "pull a human message off an error"
+ * (envelope shapes, status-code copy, "failed to fetch"). This is the single
+ * host-agnostic decoder. It is a PURE function: no fetch, no i18n, no config,
+ * no `instanceof` against host classes. It recognises the two error shapes the
+ * Xema frontend produces by their structural signature:
+ *
+ *   - the host's `ApiClientError` (`name === 'ApiClientError'`, `statusCode`,
+ *     `message`, optional `errorType`), thrown by the hand-rolled HTTP client;
+ *   - Orval's generated `ClientError` (`name === 'ClientError'`, `status`,
+ *     `message`, `body`), thrown by the generated clients. Its `body` carries
+ *     the backend `{ message, code, details }` envelope (and the workflow
+ *     wallet-missing / `session_busy` special cases).
+ *
+ * Hosts that previously kept their own `getUserFacingErrorMessage` should
+ * re-export THIS one (or delete theirs and import it) so there is a single
+ * decoder. {@link ErrorCard} defaults to it, so biomes get envelope-aware copy
+ * without wiring anything.
+ */
+
+function collapseWhitespace(value: string): string {
+  return value.split(/\s+/).join(' ').trim();
+}
+
+function getGenericErrorMessage(message: string, fallback: string): string {
+  const normalized = collapseWhitespace(message);
+  if (/failed to fetch/i.test(normalized)) {
+    return 'Could not reach the service. Check your connection and try again.';
+  }
+  return normalized || fallback;
+}
+
+function normalizeValidationMessage(rawMessage: string): string {
+  const parts = rawMessage
+    .split(',')
+    .map((part) => collapseWhitespace(part))
+    .filter(Boolean);
+
+  if (parts.length === 0) {
+    return 'Some required fields are missing or invalid. Please review your input and try again.';
+  }
+
+  const preview = parts.slice(0, 2).join('; ');
+  const suffix = parts.length > 2 ? '; and more.' : '.';
+  return `Some required fields are missing or invalid (${preview}${suffix})`;
+}
+
+/** Structural signature of the host's `ApiClientError`. */
+interface ApiClientErrorLike {
+  readonly name: string;
+  readonly statusCode: number;
+  readonly message: string;
+  readonly errorType?: string;
+}
+
+function isApiClientErrorLike(error: unknown): error is ApiClientErrorLike {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+  const record = error as Record<string, unknown>;
+  return (
+    record['name'] === 'ApiClientError' &&
+    typeof record['statusCode'] === 'number' &&
+    typeof record['message'] === 'string'
+  );
+}
+
+/** Structural signature of an Orval-generated `ClientError`. */
+interface OrvalClientErrorLike {
+  readonly name: string;
+  readonly status: number;
+  readonly message: string;
+  readonly body: unknown;
+}
+
+function isOrvalClientErrorLike(error: unknown): error is OrvalClientErrorLike {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+  const record = error as Record<string, unknown>;
+  return (
+    record['name'] === 'ClientError' &&
+    typeof record['status'] === 'number' &&
+    typeof record['message'] === 'string' &&
+    Object.hasOwn(record, 'body')
+  );
+}
+
+interface WorkflowErrorEnvelope {
+  readonly code?: string;
+  readonly message?: string;
+  readonly details?: Record<string, unknown>;
+}
+
+function readStringList(value: unknown): string[] | null {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+  if (value.some((entry) => typeof entry !== 'string')) {
+    return null;
+  }
+  return value;
+}
+
+function normalizeWorkflowWalletMissingMessage(envelope: WorkflowErrorEnvelope): string | null {
+  if (envelope.code !== 'WORKFLOW_WALLET_NOT_FOUND') {
+    return null;
+  }
+  const missing = readStringList(envelope.details?.['missing']);
+  if (missing === null || missing.length === 0) {
+    return 'One or more required wallets are missing for this project.';
+  }
+  return `Missing wallet${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}. Add ${
+    missing.length > 1 ? 'them' : 'it'
+  } in Project Settings -> Wallets.`;
+}
+
+function getApiClientErrorMessage(error: ApiClientErrorLike, fallback: string): string {
+  if (error.statusCode === 0) {
+    return collapseWhitespace(error.message) || fallback;
+  }
+  if (error.statusCode === 400) {
+    const raw = collapseWhitespace(error.message);
+    if (raw.includes(' must ') || raw.includes('regular expression')) {
+      return normalizeValidationMessage(raw);
+    }
+    return raw || 'The request is invalid. Please check your input and try again.';
+  }
+  if (error.statusCode === 401) {
+    return 'Your session expired. Please sign in again.';
+  }
+  if (error.statusCode === 403) {
+    return 'You do not have permission to perform this action.';
+  }
+  if (error.statusCode === 404) {
+    return 'The requested resource was not found.';
+  }
+  if (error.statusCode >= 500) {
+    return 'The service is temporarily unavailable. Please try again in a moment.';
+  }
+  return collapseWhitespace(error.message) || fallback;
+}
+
+function getOrvalClientErrorMessage(error: OrvalClientErrorLike, fallback: string): string {
+  if (error.status >= 500) {
+    return 'The service is temporarily unavailable. Please try again in a moment.';
+  }
+  // session-api refuses mutations while a prompt turn is in flight; the 409
+  // body is `{ error: 'session_busy', retryAfterTurnDone: true }`. Surface a
+  // clear retry hint instead of the generic "Conflict" copy.
+  if (error.status === 409) {
+    const body = error.body;
+    if (body && typeof body === 'object') {
+      const record = body as Record<string, unknown>;
+      if (record['error'] === 'session_busy') {
+        return 'Your last message is still running. Wait for the agent to finish, then try again.';
+      }
+    }
+  }
+  const body = error.body;
+  if (body && typeof body === 'object') {
+    const record = body as Record<string, unknown>;
+    const payload: WorkflowErrorEnvelope = (() => {
+      const message = record['message'];
+      if (message && typeof message === 'object') {
+        return message as WorkflowErrorEnvelope;
+      }
+      return {
+        code: typeof record['code'] === 'string' ? record['code'] : undefined,
+        message: typeof record['message'] === 'string' ? record['message'] : undefined,
+        details:
+          record['details'] && typeof record['details'] === 'object'
+            ? (record['details'] as Record<string, unknown>)
+            : undefined,
+      };
+    })();
+
+    const workflowWalletMessage = normalizeWorkflowWalletMissingMessage(payload);
+    if (workflowWalletMessage !== null) {
+      return workflowWalletMessage;
+    }
+    if (typeof payload.message === 'string' && payload.message.trim().length > 0) {
+      return collapseWhitespace(payload.message);
+    }
+    if (typeof record['message'] === 'string' && record['message'].trim().length > 0) {
+      return collapseWhitespace(record['message']);
+    }
+  }
+  return getGenericErrorMessage(error.message, fallback);
+}
+
+/**
+ * Decode any thrown value into a human, user-facing message. The single decoder
+ * for biomes, the host shell, and {@link ErrorCard}'s default.
+ *
+ * @param error Any thrown value (string, `Error`, `ApiClientError`, Orval
+ *   `ClientError`, or unknown).
+ * @param fallback Copy returned when nothing better can be extracted.
+ */
+export function getUserFacingErrorMessage(
+  error: unknown,
+  fallback = 'Something went wrong. Please try again.',
+): string {
+  if (typeof error === 'string') {
+    return collapseWhitespace(error) || fallback;
+  }
+  if (isApiClientErrorLike(error)) {
+    return getApiClientErrorMessage(error, fallback);
+  }
+  if (isOrvalClientErrorLike(error)) {
+    return getOrvalClientErrorMessage(error, fallback);
+  }
+  if (error instanceof Error) {
+    return getGenericErrorMessage(error.message, fallback);
+  }
+  return fallback;
+}

package/src/lib/biome-host/host-bridge.ts

@@ -5,6 +5,8 @@ import { createContext, useContext, type ReactNode } from 'react';
 import type { CapabilityPort } from '../capabilities';
 import type { SystemBus } from '../system-bus';
 
+import type { RealtimeSource } from './realtime-port';
+
 /**
  * `HostBridge` is the host-agnostic abstraction every frontend biome
  * receives at registration time. It decouples biome code from any
@@ -113,6 +115,26 @@ export interface HostBridgeRequestContext {
   readonly correlationId: string;
 }
 
+/**
+ * Error-decoding surface — the canonical "turn a thrown value into a
+ * user-facing message" decoder, exposed on the bridge so biomes use ONE
+ * implementation instead of each re-deriving envelope/status-code copy.
+ *
+ * The decoder is a PURE function (no host context), so the kernel also ships it
+ * directly as {@link getUserFacingErrorMessage} and {@link ErrorCard} defaults
+ * to it. It is ALSO hung off the bridge so a host can override it with a
+ * shell-specific decoder (extra error codes, i18n) without every biome wiring a
+ * prop — the bridge value is the single override point.
+ */
+export interface HostBridgeErrors {
+  /**
+   * Decode any thrown value into a user-facing message. `fallback` is returned
+   * when nothing better can be extracted. Defaults (in the kernel default
+   * bridge wiring) to {@link getUserFacingErrorMessage}.
+   */
+  getUserFacingErrorMessage(error: unknown, fallback?: string): string;
+}
+
 /**
  * Where the topbar's leading back-button takes you. Pages that have a
  * meaningful "parent context" register this; pages without one omit it
@@ -201,6 +223,28 @@ export interface HostBridge {
    * `<CapabilityProvider>` + `useCapability()` (see `../capabilities`).
    */
   readonly capabilities: CapabilityPort;
+  /**
+   * Realtime (CloudEvents over SSE) port. The HOST injects a concrete
+   * {@link RealtimeSource} backed by its realtime transport
+   * (`@xemahq/realtime-client`); biomes reach it through the kernel
+   * `useCloudEvent` / `useRealtimeStatus` / `useEventScope` hooks so biome code
+   * never imports the SSE client directly — same decoupling as `navigation`.
+   *
+   * OPTIONAL: a host without a realtime transport simply omits it; the kernel
+   * `useCloudEvent`/`useRealtimeStatus`/`useEventScope` hooks fail fast with an
+   * actionable error if a biome uses them before the host wires `bridge.realtime`.
+   */
+  readonly realtime?: RealtimeSource;
+  /**
+   * Error-decoding surface — the canonical user-facing error decoder. Defaults
+   * (in the kernel default bridge wiring) to {@link getUserFacingErrorMessage};
+   * a host MAY override it. Biomes + {@link ErrorCard} read ONE decoder instead
+   * of each re-deriving message extraction.
+   *
+   * OPTIONAL: when omitted, consumers fall back to the kernel default
+   * {@link getUserFacingErrorMessage} (which ErrorCard already uses directly).
+   */
+  readonly errors?: HostBridgeErrors;
 }
 
 export const HostBridgeContext = createContext<HostBridge | null>(null);

package/src/lib/biome-host/index.ts

@@ -26,3 +26,7 @@ export * from './host-sources';
 export * from './nav';
 export * from './biome-mode';
 export * from './agent-validation';
+export * from './realtime-port';
+export * from './realtime-hooks';
+export * from './errors';
+export * from './response-envelope';

package/src/lib/biome-host/realtime-hooks.ts

@@ -0,0 +1,74 @@
+/**
+ * Kernel-side realtime hooks. Biomes call these INSTEAD of importing the host's
+ * realtime client (`@xemahq/realtime-client`) directly, so biome code stays
+ * decoupled from the SSE transport — the same decoupling `useHostBridge`
+ * already provides for navigation / auth / capabilities.
+ *
+ * Each hook reads the host-injected {@link RealtimeSource} off
+ * `bridge.realtime` and delegates straight through. The host owns the transport
+ * (connection, token refresh, org header, scope refcounting); the kernel owns
+ * only the contract + this thin delegation.
+ */
+
+import { useHostBridge } from './host-bridge';
+import type {
+  RealtimeCloudEvent,
+  RealtimeConnectionState,
+  RealtimeScope,
+  RealtimeSource,
+} from './realtime-port';
+
+/**
+ * Resolve the host-injected realtime transport, failing fast with an actionable
+ * message if the host has not wired `bridge.realtime`. `bridge.realtime` is an
+ * optional port (a host without a realtime transport omits it), so the kernel
+ * hooks must not silently no-op — a biome that calls them expects live events.
+ */
+function requireRealtime(realtime: RealtimeSource | undefined): RealtimeSource {
+  if (!realtime) {
+    throw new Error(
+      'useCloudEvent/useRealtimeStatus/useEventScope require a realtime ' +
+        'transport, but the host has not wired `bridge.realtime`. The host ' +
+        'must provide a RealtimeSource (e.g. backed by @xemahq/realtime-client) ' +
+        'on the HostBridge to use kernel realtime hooks.',
+    );
+  }
+  return realtime;
+}
+
+/**
+ * Subscribe to delivered CloudEvents of a given `type` for the lifetime of the
+ * calling component. Pass a stable `handler` (e.g. via `useCallback`) — the
+ * host re-subscribes when the handler identity changes. Narrow `event.data`
+ * inside the handler; the kernel does not parse payloads.
+ *
+ * @example
+ *   useCloudEvent('session.lifecycle.changed', (event) => {
+ *     const data = event.data as { sessionId?: string } | undefined;
+ *     if (data?.sessionId !== sessionId) return;
+ *     refetch();
+ *   });
+ */
+export function useCloudEvent(
+  eventType: string,
+  handler: (event: RealtimeCloudEvent) => void,
+): void {
+  const bridge = useHostBridge();
+  requireRealtime(bridge.realtime).useCloudEvent(eventType, handler);
+}
+
+/** Coarse realtime connection state for a status indicator. */
+export function useRealtimeStatus(): RealtimeConnectionState {
+  const bridge = useHostBridge();
+  return requireRealtime(bridge.realtime).useRealtimeStatus();
+}
+
+/**
+ * Subscribe the connection to a project/session {@link RealtimeScope} while the
+ * calling component is mounted. Scopes are reference-counted by the host, so
+ * multiple components asking for the same scope share one server subscription.
+ */
+export function useEventScope(scope: RealtimeScope): void {
+  const bridge = useHostBridge();
+  requireRealtime(bridge.realtime).useEventScope(scope);
+}

package/src/lib/biome-host/realtime-port.ts

@@ -0,0 +1,109 @@
+/**
+ * Host-agnostic realtime (CloudEvents over SSE) port.
+ *
+ * Frontend biomes need to subscribe to server-pushed CloudEvents (session
+ * lifecycle, tool calls, notifications, …). The transport — the unified SSE
+ * connection, the Keycloak-minted bearer, the active-org header, cross-tab
+ * leader election, server-side scope subscriptions — is HOST-owned (today
+ * `@xemahq/realtime-client` wrapped by the host's `RealtimeProvider`). Biomes
+ * must NOT import that client or `EventSource` directly, exactly as they must
+ * not import `next/navigation` or `sonner`.
+ *
+ * Instead the host injects a concrete {@link RealtimeSource} when it builds the
+ * {@link HostBridge}; it is hung off `bridge.realtime`. Biomes reach it through
+ * the {@link useCloudEvent} / {@link useRealtimeStatus} / {@link useEventScope}
+ * kernel hooks — the same decoupling pattern as `bridge.navigation` /
+ * `bridge.capabilities`.
+ *
+ * Framework-agnostic: pure interface contracts, no React, no SSE, no fetch.
+ */
+
+/**
+ * The subset of the CloudEvents-shape envelope a biome handler receives.
+ *
+ * Locally typed in the kernel (deliberately NOT imported from
+ * `@xemahq/realtime-client` / `@xemahq/events`) so `@xemahq/ui-kernel` stays
+ * transport-free and host-agnostic. The host's realtime client emits an object
+ * that is structurally assignable to this — value-identical to the client's
+ * `DeliveredEvent`, kept here as the kernel's stable contract.
+ */
+export interface RealtimeCloudEvent {
+  /** CloudEvents `id` — unique per delivered event, when the server stamps it. */
+  id?: string;
+  /** CloudEvents `type`, e.g. `session.lifecycle.changed`. The subscription key. */
+  type: string;
+  /** CloudEvents `source`, e.g. `/services/activity-feed-api` or `/biomes/<id>`. */
+  source?: string;
+  /** CloudEvents `subject`, e.g. `session/<session-id>`. */
+  subject?: string;
+  /** CloudEvents `data` payload. Biomes narrow this themselves. */
+  data?: unknown;
+  /** Org-id header echoed onto every delivered envelope. */
+  ehorgid: string;
+  /** Project-id header, when the event is project-scoped. */
+  ehprojectid?: string;
+  /** User-id header, when the event is user-scoped. */
+  ehuserid?: string;
+  /** Global delivery cursor. */
+  ehglobalseq?: string;
+  /** Per-org delivery cursor. */
+  ehorgseq?: string;
+  /** Per-project delivery cursor. */
+  ehprojectseq?: string;
+  /** Per-session delivery cursor. */
+  ehsessionseq?: string;
+  /** Frontend-only invalidation hint carried alongside the envelope. */
+  __hint?: unknown;
+}
+
+/** Coarse realtime connection status for status indicators. */
+export type RealtimeStatus =
+  | 'idle'
+  | 'connecting'
+  | 'connected'
+  | 'reconnecting'
+  | 'closed';
+
+/** Coarse connection state surfaced to status UIs. */
+export interface RealtimeConnectionState {
+  readonly status: RealtimeStatus;
+  /** Latest connectionId returned by the upstream `CONNECTED` frame. */
+  readonly connectionId?: string;
+}
+
+/**
+ * A server-side scope a connection can subscribe to so it only receives the
+ * events for one project or session, rather than the full org firehose. The
+ * host's transport reference-counts identical scopes across mounts.
+ */
+export interface RealtimeScope {
+  readonly kind: 'project' | 'session';
+  readonly id: string;
+}
+
+/**
+ * Host-implemented realtime source. The host wires each method against its
+ * realtime transport (`@xemahq/realtime-client`'s `RealtimeContext`) and passes
+ * it in when building the {@link HostBridge}.
+ *
+ * Every method is a React hook (it reads transport context / state), so it
+ * MUST be called from a biome component's render — the kernel `useCloudEvent` /
+ * `useRealtimeStatus` / `useEventScope` hooks delegate straight through.
+ */
+export interface RealtimeSource {
+  /**
+   * Subscribe `handler` to every delivered CloudEvent whose `type` matches
+   * `eventType`, for the lifetime of the calling component. Per-`data` filtering
+   * (e.g. by `sessionId`) is the handler's responsibility. Mirrors the host
+   * client's `useCloudEvent`.
+   */
+  useCloudEvent(eventType: string, handler: (event: RealtimeCloudEvent) => void): void;
+  /** Coarse connection state for a status indicator. */
+  useRealtimeStatus(): RealtimeConnectionState;
+  /**
+   * Subscribe the connection's unified SSE to a project/session scope while the
+   * calling component is mounted; auto-unsubscribes on unmount. Server-side
+   * subscriptions are reference-counted by the host transport.
+   */
+  useEventScope(scope: RealtimeScope): void;
+}

package/src/lib/biome-host/response-envelope.ts

@@ -0,0 +1,69 @@
+/**
+ * Frontend mirror of the backend `ResponseEnvelopeInterceptor`.
+ *
+ * Every 2xx body the platform returns is wrapped as `{ data: T }`, or
+ * `{ data: T[], pagination }` for a paginated list (single source of truth:
+ * `@xemahq/platform-common`'s `ResponseEnvelopeInterceptor`). Orval's
+ * `custom-fetch` mutators usually peel that envelope at the HTTP boundary, but
+ * spec drift (a controller typed `T[]` that emits `{ data }`), public clients
+ * that DON'T peel, and transient partial responses leave a `.data`-wrapped or
+ * mis-shaped value where biome code expects a bare value/array — and a raw
+ * `.map` on it white-screens the route.
+ *
+ * These are the ONE shared, pure unwrap helpers — no host context, no fetch.
+ * Biomes (and the host shell's own `unwrap-list.ts`) should adopt these instead
+ * of re-implementing the guard. This is the shared helper only; adopters are
+ * migrated incrementally, not in a blanket rewrite.
+ */
+
+/**
+ * Resilient list unwrap for DISPLAY surfaces — normalises a React-Query `.data`
+ * to an array so the page renders its empty/error state instead of crashing:
+ *
+ *   - already an array        → returned as-is
+ *   - `{ data: T[] }` envelope → `value.data`
+ *   - anything else            → `[]`
+ *
+ * Deliberately NON-throwing: the query's own `isError`/`isLoading` flags drive
+ * the visible error/empty UI; this only guards the render path. For
+ * mutation/single-resource flows where an unexpected shape is a real bug, use
+ * {@link unwrapData} (fail-fast) instead.
+ */
+export function unwrapList<T>(value: unknown): T[] {
+  if (Array.isArray(value)) {
+    return value as T[];
+  }
+  if (
+    value !== null &&
+    typeof value === 'object' &&
+    Array.isArray((value as { data?: unknown }).data)
+  ) {
+    return (value as { data: T[] }).data;
+  }
+  return [];
+}
+
+/**
+ * Fail-fast single-resource unwrap. Returns `value.data` when the value is a
+ * `{ data }` envelope; returns the value unchanged when it is already the
+ * unwrapped resource (an Orval client that peeled the envelope at the boundary).
+ *
+ * Use this on mutation / single-resource flows where the response SHOULD be a
+ * concrete object — unlike {@link unwrapList}, it does not silently coerce, so
+ * a genuinely-unexpected shape surfaces as the value rather than being masked.
+ *
+ * A paginated envelope (`{ data, pagination }`) is returned INTACT — callers
+ * that need both fields read them off the returned object; peeling only `data`
+ * would drop the pagination cursor.
+ */
+export function unwrapData<T>(value: unknown): T {
+  if (
+    value !== null &&
+    typeof value === 'object' &&
+    'data' in (value as Record<string, unknown>) &&
+    !('pagination' in (value as Record<string, unknown>))
+  ) {
+    return (value as { data: T }).data;
+  }
+  return value as T;
+}

package/src/ui/chrome/ErrorCard.tsx

@@ -1,25 +1,20 @@
 import { AlertCircle, RefreshCw } from 'lucide-react';
 
+import { getUserFacingErrorMessage } from '../../lib/biome-host/errors';
 import { Button } from '../primitives/button';
 import { Card, CardContent } from '../primitives/card';
 
 /**
- * Host-agnostic error formatter. The host shell owns rich error decoding
- * (Orval envelopes, workflow error codes, …); pass its formatter via
- * `formatError` to preserve that behaviour. The default extracts a plain
- * message and is safe in any consumer.
+ * Host-agnostic error formatter. The default is the canonical, envelope-aware
+ * {@link getUserFacingErrorMessage} decoder — biomes get rich error copy with
+ * zero wiring. Pass `formatError` only to override with a host-specific decoder
+ * (extra codes, i18n); the canonical default already handles Orval envelopes,
+ * `ApiClientError`, workflow error codes, and "failed to fetch".
  */
 export type ErrorMessageFormatter = (error: unknown, fallback: string) => string;
 
-const defaultFormatError: ErrorMessageFormatter = (error, fallback) => {
-  if (typeof error === 'string') {
-    return error || fallback;
-  }
-  if (error instanceof Error && error.message) {
-    return error.message;
-  }
-  return fallback;
-};
+const defaultFormatError: ErrorMessageFormatter = (error, fallback) =>
+  getUserFacingErrorMessage(error, fallback);
 
 interface ErrorCardProps {
   error: Error | string | unknown;