@ai-matrx/messaging 0.14.0 → 0.15.1

package/dist/react.d.cts

@@ -386,11 +386,34 @@ interface AiResult {
     readonly text: string;
     readonly conversationId: string | null;
 }
+/**
+ * Facts about the open conversation the caller already holds (the inbox row
+ * and the signed-in reader). Each is sent by its offered name
+ * (`messaging.conversation`, mapped-only) beside the transcript; an absent
+ * one is omitted, never sent empty. Nothing here changes the transcript.
+ */
+interface ConversationAiContext {
+    conversationType?: ConversationType | undefined;
+    /** The name the reader sees: the group name, or the other person's name. */
+    conversationName?: string | undefined;
+    conversationCreatedAt?: string | undefined;
+    unreadCount?: number | undefined;
+    isMuted?: boolean | undefined;
+    readerUserId?: string | undefined;
+}
+/**
+ * The offered values of `ConversationAiContext`, by name. Pure, so a host that
+ * builds its own call can reuse it. `total_loaded_message_count` is the
+ * messages the caller loaded BEFORE windowing.
+ */
+declare function conversationContextVariables(context: ConversationAiContext | undefined, loadedMessageCount: number): MatrxJsonObject;
 /** What every capability takes: the conversation, and how to watch the run. */
 interface AiCallArgs {
     conversationId: ConversationId;
     messages: readonly Message[];
     participants: readonly UserSummary[];
+    /** Conversation facts sent by name beside the transcript (optional). */
+    context?: ConversationAiContext | undefined;
     signal?: AbortSignal | undefined;
     /** The accumulated answer so far, after every streamed chunk. */
     onText?: ((fullText: string) => void) | undefined;
@@ -1019,11 +1042,18 @@ interface MessagingSnapshot {
     } | null;
     /** Conversations whose last open failed, keyed by id. Cleared on the next open. */
     readonly conversationReadFailures: ReadonlyMap<ConversationId, ConversationReadFailure>;
+    /**
+     * The inbox read FAILED (and no later read succeeded). Without it a failed
+     * first read left `hasLoadedConversations` false forever — a skeleton that
+     * never resolves is a screen telling a lie (RC-B12 round 11).
+     */
+    readonly conversationsLoadError: string | null;
 }
 interface MessagingStore {
     snapshot(): MessagingSnapshot;
     subscribe(listener: (snapshot: MessagingSnapshot) => void): () => void;
     setConversations(items: readonly ConversationSummary[], hasMore: boolean): void;
+    setConversationsLoadError(message: string | null): void;
     /**
      * Switch the archive axis. Clears the list and marks it UNLOADED: the rows
      * on screen belong to the old filter, and leaving them there while the new
@@ -1133,6 +1163,8 @@ interface MessagingEngine {
      * refreshes the archived count the reveal label prints.
      */
     setArchiveFilter(next: MessagingArchiveFilter): Promise<void>;
+    /** Read the inbox again (the failed-read view's Try again). Never throws; a failure lands in the snapshot. */
+    refreshInbox(): Promise<void>;
     /** Re-read how many archived conversations exist, for the reveal's label. */
     refreshArchivedCount(): Promise<void>;
     /** Open a conversation: load its thread and subscribe to its channel. */
@@ -1376,6 +1408,10 @@ interface UseConversationsResult {
     hasMore: boolean;
     /** True only on the FIRST load; a refresh must not blank the list. */
     isInitialLoading: boolean;
+    /** The inbox read failed; the list shows the failure (never a skeleton forever, never "empty"). */
+    loadError: string | null;
+    /** Read the inbox again. */
+    retry: () => void;
     totalUnreadConversations: number;
     loadMore: () => void;
     select: (id: ConversationId) => void;
@@ -1862,4 +1898,4 @@ declare function summarizeText(content: string, maxLength?: number): string;
 /** Serialize picked references into a fence the platform's other readers accept. */
 declare function composeFence(references: readonly MatrxReference[]): string;
 
-export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerInputRenderProps, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationReadFailure, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, SearchIcon, SendIcon, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerInputRenderProps, type Conversation, type ConversationAiContext, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationReadFailure, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, SearchIcon, SendIcon, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationContextVariables, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };

package/dist/react.d.ts

@@ -386,11 +386,34 @@ interface AiResult {
     readonly text: string;
     readonly conversationId: string | null;
 }
+/**
+ * Facts about the open conversation the caller already holds (the inbox row
+ * and the signed-in reader). Each is sent by its offered name
+ * (`messaging.conversation`, mapped-only) beside the transcript; an absent
+ * one is omitted, never sent empty. Nothing here changes the transcript.
+ */
+interface ConversationAiContext {
+    conversationType?: ConversationType | undefined;
+    /** The name the reader sees: the group name, or the other person's name. */
+    conversationName?: string | undefined;
+    conversationCreatedAt?: string | undefined;
+    unreadCount?: number | undefined;
+    isMuted?: boolean | undefined;
+    readerUserId?: string | undefined;
+}
+/**
+ * The offered values of `ConversationAiContext`, by name. Pure, so a host that
+ * builds its own call can reuse it. `total_loaded_message_count` is the
+ * messages the caller loaded BEFORE windowing.
+ */
+declare function conversationContextVariables(context: ConversationAiContext | undefined, loadedMessageCount: number): MatrxJsonObject;
 /** What every capability takes: the conversation, and how to watch the run. */
 interface AiCallArgs {
     conversationId: ConversationId;
     messages: readonly Message[];
     participants: readonly UserSummary[];
+    /** Conversation facts sent by name beside the transcript (optional). */
+    context?: ConversationAiContext | undefined;
     signal?: AbortSignal | undefined;
     /** The accumulated answer so far, after every streamed chunk. */
     onText?: ((fullText: string) => void) | undefined;
@@ -1019,11 +1042,18 @@ interface MessagingSnapshot {
     } | null;
     /** Conversations whose last open failed, keyed by id. Cleared on the next open. */
     readonly conversationReadFailures: ReadonlyMap<ConversationId, ConversationReadFailure>;
+    /**
+     * The inbox read FAILED (and no later read succeeded). Without it a failed
+     * first read left `hasLoadedConversations` false forever — a skeleton that
+     * never resolves is a screen telling a lie (RC-B12 round 11).
+     */
+    readonly conversationsLoadError: string | null;
 }
 interface MessagingStore {
     snapshot(): MessagingSnapshot;
     subscribe(listener: (snapshot: MessagingSnapshot) => void): () => void;
     setConversations(items: readonly ConversationSummary[], hasMore: boolean): void;
+    setConversationsLoadError(message: string | null): void;
     /**
      * Switch the archive axis. Clears the list and marks it UNLOADED: the rows
      * on screen belong to the old filter, and leaving them there while the new
@@ -1133,6 +1163,8 @@ interface MessagingEngine {
      * refreshes the archived count the reveal label prints.
      */
     setArchiveFilter(next: MessagingArchiveFilter): Promise<void>;
+    /** Read the inbox again (the failed-read view's Try again). Never throws; a failure lands in the snapshot. */
+    refreshInbox(): Promise<void>;
     /** Re-read how many archived conversations exist, for the reveal's label. */
     refreshArchivedCount(): Promise<void>;
     /** Open a conversation: load its thread and subscribe to its channel. */
@@ -1376,6 +1408,10 @@ interface UseConversationsResult {
     hasMore: boolean;
     /** True only on the FIRST load; a refresh must not blank the list. */
     isInitialLoading: boolean;
+    /** The inbox read failed; the list shows the failure (never a skeleton forever, never "empty"). */
+    loadError: string | null;
+    /** Read the inbox again. */
+    retry: () => void;
     totalUnreadConversations: number;
     loadMore: () => void;
     select: (id: ConversationId) => void;
@@ -1862,4 +1898,4 @@ declare function summarizeText(content: string, maxLength?: number): string;
 /** Serialize picked references into a fence the platform's other readers accept. */
 declare function composeFence(references: readonly MatrxReference[]): string;
 
-export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerInputRenderProps, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationReadFailure, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, SearchIcon, SendIcon, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, AgentTag, type AiCallArgs, type AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type ComposerInputRenderProps, type Conversation, type ConversationAiContext, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationReadFailure, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, DeliveryTick, DoubleCheckIcon, type DraftMessage, EmptyState, type EngineDiagnostic, type IncomingMessageContext, type JsonObject, type JsonValue, LinkIcon, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, MessageActionChips, type MessageActionRenderProps, type MessageActionRenderer, MessageBubble, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessageWrapperProps, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingHost, type MessagingIdentity, MessagingInbox, type MessagingInboxProps, MessagingProvider, type MessagingProviderProps, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, PaperclipIcon, type Participant, type ParticipantRole, PlusIcon, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, ReferenceCard, type ReferenceRenderer, ReplyIcon, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, SearchIcon, SendIcon, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, SparklesIcon, type SupabaseLike, TABLES, type TextSegment, TypingDots, type UseComposerResult, type UseConversationResult, type UseConversationsResult, type UseMessageActionResult, type UseMessagingAiResult, type UseTypistsResult, type UserId, type UserSummary, UsersIcon, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationContextVariables, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };

package/dist/react.js

@@ -270,6 +270,20 @@ ${JSON.stringify(references, null, 2)}
 }
 
 // src/core/ai.ts
+function conversationContextVariables(context, loadedMessageCount) {
+  const values = {
+    total_loaded_message_count: loadedMessageCount
+  };
+  if (context === void 0) return values;
+  if (context.conversationType) values.conversation_type = context.conversationType;
+  if (context.conversationName) values.conversation_name = context.conversationName;
+  if (context.conversationCreatedAt)
+    values.conversation_created_at = context.conversationCreatedAt;
+  if (typeof context.unreadCount === "number") values.unread_count = context.unreadCount;
+  if (typeof context.isMuted === "boolean") values.is_muted = context.isMuted;
+  if (context.readerUserId) values.reader_user_id = context.readerUserId;
+  return values;
+}
 function unreadCutoff(messages, unreadCount) {
   if (unreadCount <= 0) return null;
   const index = messages.length - unreadCount - 1;
@@ -359,7 +373,8 @@ function createMessagingAi(options) {
       transcript_message_count: transcript.length,
       // Honest about the cut, so an agent can say "showing the last 200".
       transcript_truncated: args.messages.length > transcript.length,
-      ...args.since != null ? { unread_since: args.since } : {}
+      ...args.since != null ? { unread_since: args.since } : {},
+      ...conversationContextVariables(args.context, args.messages.length)
     };
   }
   function configured(capability) {
@@ -876,6 +891,7 @@ function createMessagingStore() {
   let threads = /* @__PURE__ */ new Map();
   let activeConversationId = null;
   let conversationReadFailures = /* @__PURE__ */ new Map();
+  let conversationsLoadError = null;
   const listeners = /* @__PURE__ */ new Set();
   let cached = null;
   function snapshot() {
@@ -889,7 +905,8 @@ function createMessagingStore() {
       totalUnreadConversations: conversations.filter((item) => item.unreadCount > 0).length,
       archiveFilter,
       archivedCount,
-      conversationReadFailures
+      conversationReadFailures,
+      conversationsLoadError
     };
     return cached;
   }
@@ -934,6 +951,12 @@ function createMessagingStore() {
       conversations = normalizeConversations(items);
       hasMoreConversations = hasMore;
       hasLoadedConversations = true;
+      conversationsLoadError = null;
+      emit();
+    },
+    setConversationsLoadError(message) {
+      if (message === conversationsLoadError) return;
+      conversationsLoadError = message;
       emit();
     },
     setArchiveFilter(next) {
@@ -1166,10 +1189,20 @@ function createMessagingEngine(options) {
   }
   async function reloadInbox() {
     if (disposed) return;
-    const page = await repository.listConversations({
-      limit: conversationPageSize,
-      archived: store.snapshot().archiveFilter
-    });
+    let page;
+    try {
+      page = await repository.listConversations({
+        limit: conversationPageSize,
+        archived: store.snapshot().archiveFilter
+      });
+    } catch (error) {
+      if (!disposed) {
+        store.setConversationsLoadError(
+          error instanceof Error ? error.message : typeof error === "string" ? error : "The conversation list could not be read."
+        );
+      }
+      throw error;
+    }
     if (disposed) return;
     conversationCursor = page.nextCursor;
     store.setConversations(page.items, page.hasMore);
@@ -1254,6 +1287,13 @@ function createMessagingEngine(options) {
         }
       });
     },
+    async refreshInbox() {
+      try {
+        await reloadInbox();
+      } catch (error) {
+        reportError(error, "inboxRefresh");
+      }
+    },
     async setArchiveFilter(next) {
       if (next === store.snapshot().archiveFilter) return;
       store.setArchiveFilter(next);
@@ -2397,7 +2437,11 @@ function useConversations() {
     hasMore: snapshot?.hasMoreConversations ?? false,
     // "Not loaded yet" is a FACT from the store, never a guess. Showing
     // "No conversations yet" before the first read is a screen telling a lie.
-    isInitialLoading: snapshot === null || !snapshot.hasLoadedConversations,
+    isInitialLoading: snapshot === null || !snapshot.hasLoadedConversations && snapshot.conversationsLoadError === null,
+    loadError: snapshot?.conversationsLoadError ?? null,
+    retry: () => {
+      void host?.engine.refreshInbox();
+    },
     totalUnreadConversations: snapshot?.totalUnreadConversations ?? 0,
     loadMore: () => {
       void host?.engine.loadMoreConversations();
@@ -2602,6 +2646,14 @@ function useMessagingAi(conversationId) {
         conversationId,
         messages: conversation.messages,
         participants: conversation.participants,
+        context: {
+          conversationType: conversation.summary?.conversation.type,
+          conversationName: conversation.summary?.displayName,
+          conversationCreatedAt: conversation.summary?.conversation.createdAt,
+          unreadCount: conversation.summary?.unreadCount,
+          isMuted: conversation.summary?.isMuted,
+          readerUserId: host?.identity.userId || void 0
+        },
         signal: controller.signal,
         // Live progress. Aborted runs stop painting immediately — a cancelled
         // answer must not keep growing on screen.
@@ -2984,6 +3036,7 @@ function EmptyState(props) {
 }
 
 // src/react/components.tsx
+import { ErrorBox } from "@ai-matrx/design-system";
 import { Fragment, jsx as jsx4, jsxs as jsxs2 } from "react/jsx-runtime";
 var AI_LABELS = {
   catchUp: "Catch me up",
@@ -3001,7 +3054,9 @@ function ConversationList(props) {
     activeConversationId,
     archiveFilter,
     setArchiveFilter,
-    archivedCount
+    archivedCount,
+    loadError,
+    retry
   } = useConversations();
   const RowChrome = useMessagingHost()?.wrapConversationRow ?? null;
   const [query, setQuery] = useState2("");
@@ -3066,7 +3121,20 @@ function ConversationList(props) {
       }
     ) }) : null,
     /* @__PURE__ */ jsxs2("div", { className: "mx-msg__scroll", children: [
-      isInitialLoading ? /* @__PURE__ */ jsx4(ConversationSkeleton, {}) : visible.length === 0 ? /* @__PURE__ */ jsx4(
+      isInitialLoading ? /* @__PURE__ */ jsx4(ConversationSkeleton, {}) : loadError !== null && visible.length === 0 ? (
+        // A failed read resolves to the failure — never a skeleton forever,
+        // never "No conversations yet" (RC-B12 round 11). ErrorBox is the
+        // design-system error slot: the host fills it with its menu.
+        /* @__PURE__ */ jsx4(
+          ReadFailureBox,
+          {
+            title: "Couldn't load your conversations",
+            message: loadError,
+            operation: "List your conversations",
+            onRetry: retry
+          }
+        )
+      ) : visible.length === 0 ? /* @__PURE__ */ jsx4(
         EmptyState,
         {
           title: query.length > 0 ? "No matches" : showingArchive ? "No archived conversations" : "No conversations yet",
@@ -3243,10 +3311,11 @@ function ConversationView(props) {
         body: "It doesn't exist, or you aren't a member of it."
       }
     ) : conversation.error !== null && messages.length === 0 ? /* @__PURE__ */ jsx4(
-      EmptyState,
+      ReadFailureBox,
       {
         title: "Couldn't load this conversation",
-        body: "Check your connection, then open it again."
+        message: conversation.error.message || "Check your connection, then open it again.",
+        operation: "Open this conversation"
       }
     ) : messages.length === 0 ? /* @__PURE__ */ jsx4(EmptyState, { title: "No messages yet", body: "Say something to get started." }) : /* @__PURE__ */ jsxs2("div", { className: "mx-msg__messages", children: [
       conversation.hasMoreOlder ? /* @__PURE__ */ jsx4(
@@ -3577,6 +3646,29 @@ function MessagingInbox(props) {
     }
   );
 }
+function ReadFailureBox({
+  title,
+  message,
+  operation,
+  onRetry
+}) {
+  return /* @__PURE__ */ jsxs2("div", { className: "mx-msg__empty", role: "alert", children: [
+    /* @__PURE__ */ jsx4(
+      ErrorBox,
+      {
+        as: "div",
+        title,
+        message,
+        operation,
+        origin: "messaging",
+        style: { color: "var(--mx-msg-danger)", fontWeight: 600 },
+        children: title
+      }
+    ),
+    /* @__PURE__ */ jsx4("p", { children: message }),
+    onRetry ? /* @__PURE__ */ jsx4("button", { type: "button", className: "mx-msg__button mx-msg__button--ghost", onClick: onRetry, children: "Try again" }) : null
+  ] });
+}
 export {
   AgentTag,
   AlertIcon,
@@ -3621,6 +3713,7 @@ export {
   asOrganizationId,
   asUserId,
   composeFence,
+  conversationContextVariables,
   conversationTopic,
   createActionRegistry,
   createMemoryOutboxStorage,