@ai-matrx/messaging 0.9.0 → 0.10.1

package/dist/react.d.cts

@@ -1,5 +1,5 @@
 import { ReactNode, ComponentType, SVGProps } from 'react';
-import { MatrxTransport } from '@ai-matrx/agents/matrx';
+import { MatrxJsonObject, MatrxTransport } from '@ai-matrx/agents/matrx';
 import { RealtimeClientLike, RealtimeManager } from '@ai-matrx/realtime';
 
 /**
@@ -285,27 +285,59 @@ declare function createActionRegistry(): ActionRegistry;
  * every conversation it touches. Every call below sends `variables` and either
  * a short human-shaped `user_input` or none.
  *
- * 🚨 **AGENT DEFINITIONS LIVE IN THE DATABASE.** The package takes agent IDs as
- * injected identity. When an id is not configured the capability reports
- * `unavailable` WITH the remedy — it never silently no-ops, and the UI hides
- * the action rather than offering a dead button (no dead ends).
+ * 🚨 **AGENT DEFINITIONS LIVE IN THE DATABASE.** The package takes an injected
+ * IDENTITY per capability — the database agent id and the settings that came
+ * with it — and nothing else. When an identity is not configured the capability
+ * reports `unavailable` WITH the remedy; it never silently no-ops, and the UI
+ * hides the action rather than offering a dead button (no dead ends).
+ *
+ * 🚨 **AN IDENTITY IS BOTH HALVES.** A host that resolves a capability's agent
+ * from its own switching layer resolves a PAIR: which agent, and the settings
+ * that layer decided for it. Taking only the id silently drops the settings
+ * half, so `configOverrides` rides with the id and is sent verbatim as the
+ * turn's `config_overrides`.
+ *
+ * 🚨 **A RUN THE USER WATCHES STREAMS.** Every call takes `onText` and reports
+ * the accumulated answer as it arrives. A skeleton that sits until a run
+ * finishes is a spinner standing in for an answer; the caller renders the
+ * partial text instead.
  */
 
 /**
- * Which platform agent backs each capability. Every field is a DATABASE row id
- * supplied by the host; an omitted one disables exactly that capability.
+ * WHO fulfils one capability, as the host resolved it. Both halves travel
+ * together: an id alone is half an answer whenever the host's switching layer
+ * also decided settings for the job.
+ */
+interface MessagingAgentIdentity {
+    /** The DATABASE agent row id. Never a name, never a prompt. */
+    readonly agentId: string;
+    /**
+     * The settings half, in LLMParams shape, sent verbatim as the turn's
+     * `config_overrides`. `null`/omitted = the agent's own settings stand.
+     */
+    readonly configOverrides?: MatrxJsonObject | null | undefined;
+}
+/**
+ * Which platform agent backs each capability. Every field is an identity the
+ * host injects; an omitted one disables exactly that capability.
  */
 interface MessagingAgents {
-    readonly catchUp?: string | undefined;
-    readonly summarize?: string | undefined;
-    readonly actionItems?: string | undefined;
-    readonly draftReply?: string | undefined;
+    readonly catchUp?: MessagingAgentIdentity | undefined;
+    readonly summarize?: MessagingAgentIdentity | undefined;
+    readonly actionItems?: MessagingAgentIdentity | undefined;
+    readonly draftReply?: MessagingAgentIdentity | undefined;
 }
 interface MessagingAiOptions {
     transport: MatrxTransport;
     organizationId: string;
     agents: MessagingAgents;
-    /** Stable source slugs so server-side analytics can see where a run came from. */
+    /**
+     * The producer slugs stamped on every run. 🚨 The AI Matrx server keeps a
+     * REGISTER of legal producers and refuses an unregistered one with a 422, so
+     * the defaults below are placeholders that will NOT survive a real server —
+     * only the host knows its registered slugs. Not analytics garnish: an
+     * unstamped or unregistered run is a refused run.
+     */
     sourceApp?: string | undefined;
     sourceFeature?: string | undefined;
     /** Cap on how much transcript is sent. Default 200 messages. */
@@ -317,38 +349,44 @@ interface AiResult {
     readonly text: string;
     readonly conversationId: string | null;
 }
+/** What every capability takes: the conversation, and how to watch the run. */
+interface AiCallArgs {
+    conversationId: ConversationId;
+    messages: readonly Message[];
+    participants: readonly UserSummary[];
+    signal?: AbortSignal | undefined;
+    /** The accumulated answer so far, after every streamed chunk. */
+    onText?: ((fullText: string) => void) | undefined;
+}
 interface MessagingAi {
     /** Which capabilities this host actually configured. Drives what the UI offers. */
     available(): readonly AiCapability[];
     isAvailable(capability: AiCapability): boolean;
-    catchMeUp(args: {
-        conversationId: ConversationId;
-        messages: readonly Message[];
-        participants: readonly UserSummary[];
+    catchMeUp(args: AiCallArgs & {
+        /**
+         * Exclusive cutoff — only messages after it are sent. `null` means the
+         * caller genuinely has no read mark and the whole window applies.
+         */
         since: string | null;
-        signal?: AbortSignal;
-    }): Promise<AiResult>;
-    summarize(args: {
-        conversationId: ConversationId;
-        messages: readonly Message[];
-        participants: readonly UserSummary[];
-        signal?: AbortSignal;
     }): Promise<AiResult>;
-    extractActionItems(args: {
-        conversationId: ConversationId;
-        messages: readonly Message[];
-        participants: readonly UserSummary[];
-        signal?: AbortSignal;
-    }): Promise<AiResult>;
-    draftReply(args: {
-        conversationId: ConversationId;
-        messages: readonly Message[];
-        participants: readonly UserSummary[];
+    summarize(args: AiCallArgs): Promise<AiResult>;
+    extractActionItems(args: AiCallArgs): Promise<AiResult>;
+    draftReply(args: AiCallArgs & {
         /** What the human asked for, if anything — this IS a human utterance. */
         instruction?: string | undefined;
-        signal?: AbortSignal;
     }): Promise<AiResult>;
 }
+/**
+ * The exclusive cutoff "what did I miss" means, derived from what the store
+ * already knows: the message just BEFORE the first unread one. No unread
+ * messages, or a loaded window that does not reach back that far, means there
+ * is no honest cutoff — the whole window applies, and the caller says so by
+ * passing `null` rather than guessing a timestamp.
+ *
+ * Framework-free on purpose: a Redux or React Native consumer must not have to
+ * re-derive what "unread" means.
+ */
+declare function unreadCutoff(messages: readonly Message[], unreadCount: number): string | null;
 declare function createMessagingAi(options: MessagingAiOptions): MessagingAi;
 
 /**
@@ -947,8 +985,23 @@ interface MessagingProviderProps {
      * the AI actions then do not render at all (never a dead button).
      */
     transport?: MatrxTransport | undefined;
-    /** Which database agent backs each AI capability. */
+    /** Which database agent backs each AI capability, with its settings. */
     agents?: MessagingAgents | undefined;
+    /**
+     * How much transcript rides an AI call, in messages. The package's 200 is a
+     * starting value, not a taste: a host with a knob for it passes the resolved
+     * number so an organization can decide.
+     */
+    maxTranscriptMessages?: number | undefined;
+    /**
+     * 🚨 REQUIRED IN PRACTICE FOR AI. The producer slugs stamped on every AI run.
+     * The AI Matrx server keeps a REGISTER of legal producers and REFUSES an
+     * unregistered one with a 422 — so this package's placeholder defaults
+     * (`ai-matrx` / `messaging.<capability>`) fail every call against a real
+     * server. Only the host knows its registered slugs; pass them.
+     */
+    sourceApp?: string | undefined;
+    sourceFeature?: string | undefined;
     /** Handlers for actionable messages. Registered once per handler identity. */
     actions?: readonly ActionHandler<never>[] | undefined;
     /**
@@ -1051,6 +1104,14 @@ declare function useOnlineUserIds(conversationId: ConversationId | null): Readon
 interface UseMessagingAiResult {
     available: readonly AiCapability[];
     isRunning: boolean;
+    /**
+     * The answer as it arrives, while `isRunning`. A surface renders THIS, not a
+     * skeleton: a placeholder that sits until a run finishes is a spinner
+     * standing in for an answer. Empty string until the first chunk lands.
+     */
+    partialText: string;
+    /** Which capability is running (or produced `result`). */
+    activeCapability: AiCapability | null;
     result: AiResult | null;
     error: string | null;
     run: (capability: AiCapability, args?: {
@@ -1458,4 +1519,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 AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, 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 MessagingAgents, type MessagingAi, type MessagingAiOptions, 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, type SchemaLike, SearchIcon, SendIcon, 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, createWebOutboxStorage, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, 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 Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, 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 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, type SchemaLike, SearchIcon, SendIcon, 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, createWebOutboxStorage, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode, ComponentType, SVGProps } from 'react';
-import { MatrxTransport } from '@ai-matrx/agents/matrx';
+import { MatrxJsonObject, MatrxTransport } from '@ai-matrx/agents/matrx';
 import { RealtimeClientLike, RealtimeManager } from '@ai-matrx/realtime';
 
 /**
@@ -285,27 +285,59 @@ declare function createActionRegistry(): ActionRegistry;
  * every conversation it touches. Every call below sends `variables` and either
  * a short human-shaped `user_input` or none.
  *
- * 🚨 **AGENT DEFINITIONS LIVE IN THE DATABASE.** The package takes agent IDs as
- * injected identity. When an id is not configured the capability reports
- * `unavailable` WITH the remedy — it never silently no-ops, and the UI hides
- * the action rather than offering a dead button (no dead ends).
+ * 🚨 **AGENT DEFINITIONS LIVE IN THE DATABASE.** The package takes an injected
+ * IDENTITY per capability — the database agent id and the settings that came
+ * with it — and nothing else. When an identity is not configured the capability
+ * reports `unavailable` WITH the remedy; it never silently no-ops, and the UI
+ * hides the action rather than offering a dead button (no dead ends).
+ *
+ * 🚨 **AN IDENTITY IS BOTH HALVES.** A host that resolves a capability's agent
+ * from its own switching layer resolves a PAIR: which agent, and the settings
+ * that layer decided for it. Taking only the id silently drops the settings
+ * half, so `configOverrides` rides with the id and is sent verbatim as the
+ * turn's `config_overrides`.
+ *
+ * 🚨 **A RUN THE USER WATCHES STREAMS.** Every call takes `onText` and reports
+ * the accumulated answer as it arrives. A skeleton that sits until a run
+ * finishes is a spinner standing in for an answer; the caller renders the
+ * partial text instead.
  */
 
 /**
- * Which platform agent backs each capability. Every field is a DATABASE row id
- * supplied by the host; an omitted one disables exactly that capability.
+ * WHO fulfils one capability, as the host resolved it. Both halves travel
+ * together: an id alone is half an answer whenever the host's switching layer
+ * also decided settings for the job.
+ */
+interface MessagingAgentIdentity {
+    /** The DATABASE agent row id. Never a name, never a prompt. */
+    readonly agentId: string;
+    /**
+     * The settings half, in LLMParams shape, sent verbatim as the turn's
+     * `config_overrides`. `null`/omitted = the agent's own settings stand.
+     */
+    readonly configOverrides?: MatrxJsonObject | null | undefined;
+}
+/**
+ * Which platform agent backs each capability. Every field is an identity the
+ * host injects; an omitted one disables exactly that capability.
  */
 interface MessagingAgents {
-    readonly catchUp?: string | undefined;
-    readonly summarize?: string | undefined;
-    readonly actionItems?: string | undefined;
-    readonly draftReply?: string | undefined;
+    readonly catchUp?: MessagingAgentIdentity | undefined;
+    readonly summarize?: MessagingAgentIdentity | undefined;
+    readonly actionItems?: MessagingAgentIdentity | undefined;
+    readonly draftReply?: MessagingAgentIdentity | undefined;
 }
 interface MessagingAiOptions {
     transport: MatrxTransport;
     organizationId: string;
     agents: MessagingAgents;
-    /** Stable source slugs so server-side analytics can see where a run came from. */
+    /**
+     * The producer slugs stamped on every run. 🚨 The AI Matrx server keeps a
+     * REGISTER of legal producers and refuses an unregistered one with a 422, so
+     * the defaults below are placeholders that will NOT survive a real server —
+     * only the host knows its registered slugs. Not analytics garnish: an
+     * unstamped or unregistered run is a refused run.
+     */
     sourceApp?: string | undefined;
     sourceFeature?: string | undefined;
     /** Cap on how much transcript is sent. Default 200 messages. */
@@ -317,38 +349,44 @@ interface AiResult {
     readonly text: string;
     readonly conversationId: string | null;
 }
+/** What every capability takes: the conversation, and how to watch the run. */
+interface AiCallArgs {
+    conversationId: ConversationId;
+    messages: readonly Message[];
+    participants: readonly UserSummary[];
+    signal?: AbortSignal | undefined;
+    /** The accumulated answer so far, after every streamed chunk. */
+    onText?: ((fullText: string) => void) | undefined;
+}
 interface MessagingAi {
     /** Which capabilities this host actually configured. Drives what the UI offers. */
     available(): readonly AiCapability[];
     isAvailable(capability: AiCapability): boolean;
-    catchMeUp(args: {
-        conversationId: ConversationId;
-        messages: readonly Message[];
-        participants: readonly UserSummary[];
+    catchMeUp(args: AiCallArgs & {
+        /**
+         * Exclusive cutoff — only messages after it are sent. `null` means the
+         * caller genuinely has no read mark and the whole window applies.
+         */
         since: string | null;
-        signal?: AbortSignal;
-    }): Promise<AiResult>;
-    summarize(args: {
-        conversationId: ConversationId;
-        messages: readonly Message[];
-        participants: readonly UserSummary[];
-        signal?: AbortSignal;
     }): Promise<AiResult>;
-    extractActionItems(args: {
-        conversationId: ConversationId;
-        messages: readonly Message[];
-        participants: readonly UserSummary[];
-        signal?: AbortSignal;
-    }): Promise<AiResult>;
-    draftReply(args: {
-        conversationId: ConversationId;
-        messages: readonly Message[];
-        participants: readonly UserSummary[];
+    summarize(args: AiCallArgs): Promise<AiResult>;
+    extractActionItems(args: AiCallArgs): Promise<AiResult>;
+    draftReply(args: AiCallArgs & {
         /** What the human asked for, if anything — this IS a human utterance. */
         instruction?: string | undefined;
-        signal?: AbortSignal;
     }): Promise<AiResult>;
 }
+/**
+ * The exclusive cutoff "what did I miss" means, derived from what the store
+ * already knows: the message just BEFORE the first unread one. No unread
+ * messages, or a loaded window that does not reach back that far, means there
+ * is no honest cutoff — the whole window applies, and the caller says so by
+ * passing `null` rather than guessing a timestamp.
+ *
+ * Framework-free on purpose: a Redux or React Native consumer must not have to
+ * re-derive what "unread" means.
+ */
+declare function unreadCutoff(messages: readonly Message[], unreadCount: number): string | null;
 declare function createMessagingAi(options: MessagingAiOptions): MessagingAi;
 
 /**
@@ -947,8 +985,23 @@ interface MessagingProviderProps {
      * the AI actions then do not render at all (never a dead button).
      */
     transport?: MatrxTransport | undefined;
-    /** Which database agent backs each AI capability. */
+    /** Which database agent backs each AI capability, with its settings. */
     agents?: MessagingAgents | undefined;
+    /**
+     * How much transcript rides an AI call, in messages. The package's 200 is a
+     * starting value, not a taste: a host with a knob for it passes the resolved
+     * number so an organization can decide.
+     */
+    maxTranscriptMessages?: number | undefined;
+    /**
+     * 🚨 REQUIRED IN PRACTICE FOR AI. The producer slugs stamped on every AI run.
+     * The AI Matrx server keeps a REGISTER of legal producers and REFUSES an
+     * unregistered one with a 422 — so this package's placeholder defaults
+     * (`ai-matrx` / `messaging.<capability>`) fail every call against a real
+     * server. Only the host knows its registered slugs; pass them.
+     */
+    sourceApp?: string | undefined;
+    sourceFeature?: string | undefined;
     /** Handlers for actionable messages. Registered once per handler identity. */
     actions?: readonly ActionHandler<never>[] | undefined;
     /**
@@ -1051,6 +1104,14 @@ declare function useOnlineUserIds(conversationId: ConversationId | null): Readon
 interface UseMessagingAiResult {
     available: readonly AiCapability[];
     isRunning: boolean;
+    /**
+     * The answer as it arrives, while `isRunning`. A surface renders THIS, not a
+     * skeleton: a placeholder that sits until a run finishes is a spinner
+     * standing in for an answer. Empty string until the first chunk lands.
+     */
+    partialText: string;
+    /** Which capability is running (or produced `result`). */
+    activeCapability: AiCapability | null;
     result: AiResult | null;
     error: string | null;
     run: (capability: AiCapability, args?: {
@@ -1458,4 +1519,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 AiCapability, type AiResult, AlertIcon, type Attachment, Avatar, BotIcon, CheckIcon, ChevronLeftIcon, type ClientMessageId, ClockIcon, CloseIcon, Composer, type Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, 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 MessagingAgents, type MessagingAi, type MessagingAiOptions, 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, type SchemaLike, SearchIcon, SendIcon, 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, createWebOutboxStorage, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, 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 Conversation, type ConversationCursor, type ConversationId, ConversationList, type ConversationListProps, type ConversationRowWrapperProps, ConversationSkeleton, type ConversationSummary, type ConversationThread, type ConversationType, ConversationView, type ConversationViewProps, 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 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, type SchemaLike, SearchIcon, SendIcon, 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, createWebOutboxStorage, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, unreadCutoff, useComposer, useConversation, useConversations, useMessageAction, useMessagingAi, useMessagingHost, useMessagingSnapshot, useOnlineUserIds, useRequiredMessagingHost, useTypists };

package/dist/react.js

@@ -261,6 +261,12 @@ ${JSON.stringify(references, null, 2)}
 }
 
 // src/core/ai.ts
+function unreadCutoff(messages, unreadCount) {
+  if (unreadCount <= 0) return null;
+  const index = messages.length - unreadCount - 1;
+  if (index < 0) return null;
+  return messages[index]?.createdAt ?? null;
+}
 function nameOf(participants, senderId) {
   return participants.find((p) => p.userId === senderId)?.displayName ?? senderId;
 }
@@ -281,22 +287,23 @@ function buildTranscript(messages, participants, limit, since) {
 }
 function createMessagingAi(options) {
   const limit = options.maxTranscriptMessages ?? 200;
-  function agentFor(capability) {
-    const agentId = options.agents[capability];
-    if (typeof agentId !== "string" || agentId.length === 0) {
+  function identityFor(capability) {
+    const identity = options.agents[capability];
+    if (identity === void 0 || identity.agentId.length === 0) {
       throw new MessagingError(
         "misconfigured",
         `Messaging AI capability "${capability}" has no agent configured`,
-        `Pass agents={{ ${capability}: "<agent-id>" }} to <MessagingProvider>. Agent definitions live in the database, never in this package \u2014 the id is the only part a host injects. Until then the UI hides this action rather than offering a button that cannot work.`
+        `Pass agents={{ ${capability}: { agentId: "<agent-id>" } }} to <MessagingProvider>. Agent definitions live in the database, never in this package \u2014 the identity is the only part a host injects. Until then the UI hides this action rather than offering a button that cannot work.`
       );
     }
-    return agentId;
+    return identity;
   }
-  async function run(capability, variables, userInput, signal) {
-    const agentId = agentFor(capability);
+  async function run(capability, variables, userInput, signal, onText) {
+    const identity = identityFor(capability);
+    const overrides = identity.configOverrides;
     const completed = await runAgentToCompletion(
       options.transport,
-      agentId,
+      identity.agentId,
       {
         ...newEphemeralConversationStart(),
         organization_id: options.organizationId,
@@ -305,9 +312,15 @@ function createMessagingAi(options) {
         initiation: "user",
         // THE USER-INPUT LAW: structured content is NEVER here.
         ...userInput !== null ? { user_input: userInput } : {},
+        // The settings half of the injected identity, verbatim. An absent one
+        // is OMITTED rather than sent as null: the agent's own settings stand.
+        ...overrides != null ? { config_overrides: overrides } : {},
         variables
       },
-      signal !== void 0 ? { signal } : {}
+      {
+        ...signal !== void 0 ? { signal } : {},
+        ...onText !== void 0 ? { onChunk: onText } : {}
+      }
     );
     return {
       capability,
@@ -340,27 +353,26 @@ function createMessagingAi(options) {
       ...args.since != null ? { unread_since: args.since } : {}
     };
   }
+  function configured(capability) {
+    const identity = options.agents[capability];
+    return identity !== void 0 && identity.agentId.length > 0;
+  }
   return {
     available: () => ["catchUp", "summarize", "actionItems", "draftReply"].filter(
-      (capability) => {
-        const id = options.agents[capability];
-        return typeof id === "string" && id.length > 0;
-      }
+      configured
     ),
-    isAvailable(capability) {
-      const id = options.agents[capability];
-      return typeof id === "string" && id.length > 0;
-    },
-    catchMeUp: (args) => run("catchUp", variablesFor(args), null, args.signal),
-    summarize: (args) => run("summarize", variablesFor(args), null, args.signal),
-    extractActionItems: (args) => run("actionItems", variablesFor(args), null, args.signal),
+    isAvailable: configured,
+    catchMeUp: (args) => run("catchUp", variablesFor(args), null, args.signal, args.onText),
+    summarize: (args) => run("summarize", variablesFor(args), null, args.signal, args.onText),
+    extractActionItems: (args) => run("actionItems", variablesFor(args), null, args.signal, args.onText),
     draftReply: (args) => run(
       "draftReply",
       variablesFor(args),
       // The ONE genuine human utterance in this module: what the user asked
       // the drafter for. Everything else rode `variables`.
       args.instruction !== void 0 && args.instruction.trim().length > 0 ? args.instruction.trim() : null,
-      args.signal
+      args.signal,
+      args.onText
     )
   };
 }
@@ -1804,14 +1816,28 @@ function MessagingRuntime(props) {
   }, [engine]);
   const transport = props.transport;
   const agents = props.agents;
+  const maxTranscriptMessages = props.maxTranscriptMessages;
+  const sourceApp = props.sourceApp;
+  const sourceFeature = props.sourceFeature;
   const ai = useMemo(() => {
     if (transport === void 0 || agents === void 0 || !ready) return null;
     return createMessagingAi({
       transport,
       organizationId,
-      agents
+      agents,
+      ...maxTranscriptMessages !== void 0 ? { maxTranscriptMessages } : {},
+      ...sourceApp !== void 0 ? { sourceApp } : {},
+      ...sourceFeature !== void 0 ? { sourceFeature } : {}
     });
-  }, [transport, agents, ready, organizationId]);
+  }, [
+    transport,
+    agents,
+    ready,
+    organizationId,
+    maxTranscriptMessages,
+    sourceApp,
+    sourceFeature
+  ]);
   const renderers = props.actionRenderers;
   const rendererMap = useMemo(() => {
     const map = /* @__PURE__ */ new Map();
@@ -2139,6 +2165,10 @@ function useMessagingAi(conversationId) {
   const host = useMessagingHost();
   const conversation = useConversation(conversationId);
   const [isRunning, setRunning] = useState(false);
+  const [partialText, setPartialText] = useState("");
+  const [activeCapability, setActiveCapability] = useState(
+    null
+  );
   const [result, setResult] = useState(null);
   const [error, setError] = useState(null);
   const abortRef = useRef2(null);
@@ -2152,11 +2182,15 @@ function useMessagingAi(conversationId) {
   return {
     available: ai?.available() ?? [],
     isRunning,
+    partialText,
+    activeCapability,
     result,
     error,
     clear: () => {
       setResult(null);
       setError(null);
+      setPartialText("");
+      setActiveCapability(null);
     },
     run: (capability, args = {}) => {
       if (ai === null || conversationId === null) return;
@@ -2165,22 +2199,32 @@ function useMessagingAi(conversationId) {
       abortRef.current = controller;
       setRunning(true);
       setError(null);
+      setResult(null);
+      setPartialText("");
+      setActiveCapability(capability);
       const base = {
         conversationId,
         messages: conversation.messages,
         participants: conversation.participants,
-        signal: controller.signal
+        signal: controller.signal,
+        // Live progress. Aborted runs stop painting immediately — a cancelled
+        // answer must not keep growing on screen.
+        onText: (text) => {
+          if (!controller.signal.aborted) setPartialText(text);
+        }
       };
       const call = () => {
         switch (capability) {
-          case "catchUp": {
-            const summary = conversation.summary;
-            const self = summary?.participants.find(
-              (participant) => participant.userId === host?.identity.userId
-            );
-            void self;
-            return ai.catchMeUp({ ...base, since: null });
-          }
+          case "catchUp":
+            return ai.catchMeUp({
+              ...base,
+              // "What did I miss" is about the UNREAD tail. Sending the whole
+              // window made this capability a second Summarize.
+              since: unreadCutoff(
+                conversation.messages,
+                conversation.summary?.unreadCount ?? 0
+              )
+            });
           case "summarize":
             return ai.summarize(base);
           case "actionItems":
@@ -2703,7 +2747,16 @@ function ConversationView(props) {
       },
       capability
     )) }) : null,
-    ai.isRunning ? /* @__PURE__ */ jsx4("p", { className: "mx-msg__ai-output", "aria-busy": "true", children: /* @__PURE__ */ jsx4("span", { className: "mx-msg__skeleton", style: { display: "block", height: 11, width: "72%" } }) }) : ai.error !== null ? /* @__PURE__ */ jsx4("p", { className: "mx-msg__ai-output", style: { color: "var(--mx-msg-danger)" }, children: ai.error }) : ai.result !== null ? /* @__PURE__ */ jsxs2("p", { className: "mx-msg__ai-output", children: [
+    ai.isRunning ? /* @__PURE__ */ jsx4("p", { className: "mx-msg__ai-output", "aria-busy": "true", "aria-live": "polite", children: ai.partialText.length > 0 ? ai.partialText : /* @__PURE__ */ jsxs2(Fragment, { children: [
+      /* @__PURE__ */ jsx4("span", { className: "mx-msg__ai-output-label", children: ai.activeCapability !== null ? `${AI_LABELS[ai.activeCapability]}\u2026` : "Working\u2026" }),
+      /* @__PURE__ */ jsx4(
+        "span",
+        {
+          className: "mx-msg__skeleton",
+          style: { display: "block", height: 11, width: "72%" }
+        }
+      )
+    ] }) }) : ai.error !== null ? /* @__PURE__ */ jsx4("p", { className: "mx-msg__ai-output", style: { color: "var(--mx-msg-danger)" }, children: ai.error }) : ai.result !== null ? /* @__PURE__ */ jsxs2("p", { className: "mx-msg__ai-output", children: [
       ai.result.text,
       /* @__PURE__ */ jsx4(
         "button",
@@ -3106,6 +3159,7 @@ export {
   resolveActor,
   splitText,
   summarizeText,
+  unreadCutoff,
   useComposer,
   useConversation,
   useConversations,