@ai-matrx/messaging 0.14.0 → 0.15.1

package/dist/index.d.cts

@@ -412,11 +412,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;
@@ -1122,11 +1145,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
@@ -1236,6 +1266,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. */
@@ -1390,4 +1422,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, type AiCallArgs, type AiCapability, type AiResult, type Attachment, type ClientMessageId, type Conversation, type ConversationCursor, type ConversationId, type ConversationReadFailure, type ConversationSummary, type ConversationThread, type ConversationType, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, type DraftMessage, type EngineDiagnostic, type JsonObject, type JsonValue, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingIdentity, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, type Participant, type ParticipantRole, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, type SupabaseLike, TABLES, type TextSegment, type UserId, type UserSummary, 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 };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, type AiCallArgs, type AiCapability, type AiResult, type Attachment, type ClientMessageId, type Conversation, type ConversationAiContext, type ConversationCursor, type ConversationId, type ConversationReadFailure, type ConversationSummary, type ConversationThread, type ConversationType, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, type DraftMessage, type EngineDiagnostic, type JsonObject, type JsonValue, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingIdentity, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, type Participant, type ParticipantRole, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, type SupabaseLike, TABLES, type TextSegment, type UserId, type UserSummary, 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 };

package/dist/index.d.ts

@@ -412,11 +412,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;
@@ -1122,11 +1145,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
@@ -1236,6 +1266,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. */
@@ -1390,4 +1422,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, type AiCallArgs, type AiCapability, type AiResult, type Attachment, type ClientMessageId, type Conversation, type ConversationCursor, type ConversationId, type ConversationReadFailure, type ConversationSummary, type ConversationThread, type ConversationType, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, type DraftMessage, type EngineDiagnostic, type JsonObject, type JsonValue, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingIdentity, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, type Participant, type ParticipantRole, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, type SupabaseLike, TABLES, type TextSegment, type UserId, type UserSummary, 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 };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, type AiCallArgs, type AiCapability, type AiResult, type Attachment, type ClientMessageId, type Conversation, type ConversationAiContext, type ConversationCursor, type ConversationId, type ConversationReadFailure, type ConversationSummary, type ConversationThread, type ConversationType, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, type DraftMessage, type EngineDiagnostic, type JsonObject, type JsonValue, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingIdentity, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, type Participant, type ParticipantRole, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, type SupabaseLike, TABLES, type TextSegment, type UserId, type UserSummary, 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 };

package/dist/index.js

@@ -323,6 +323,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;
@@ -412,7 +426,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) {
@@ -975,6 +990,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() {
@@ -988,7 +1004,8 @@ function createMessagingStore() {
       totalUnreadConversations: conversations.filter((item) => item.unreadCount > 0).length,
       archiveFilter,
       archivedCount,
-      conversationReadFailures
+      conversationReadFailures,
+      conversationsLoadError
     };
     return cached;
   }
@@ -1033,6 +1050,12 @@ function createMessagingStore() {
       conversations = normalizeConversations(items);
       hasMoreConversations = hasMore;
       hasLoadedConversations = true;
+      conversationsLoadError = null;
+      emit();
+    },
+    setConversationsLoadError(message) {
+      if (message === conversationsLoadError) return;
+      conversationsLoadError = message;
       emit();
     },
     setArchiveFilter(next) {
@@ -1265,10 +1288,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);
@@ -1353,6 +1386,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);
@@ -2201,6 +2241,7 @@ export {
   asOrganizationId,
   asUserId,
   composeFence,
+  conversationContextVariables,
   conversationTopic,
   createActionRegistry,
   createMemoryOutboxStorage,