OpenMax
Free Trial

Host capabilities

Every member of every ChatHost capability — signature, required or not, and whether a failure should throw, return empty or return undefined.

Host capabilities

Each field of the host (ChatHost) is a capability. This page lists their members; the data types in parameters and return values are in the Data model. What each capability switches on and what happens without it: Capabilities. All types are exported from @openmaxai/chat/host (ChatComposerPreferencesPort and ChatSendShortcut: Planned).

Capability Required Members
identity Yes This page
messaging Yes This page
drafts Yes This page
inboundDelivery Yes This page
render Yes This page
attention Yes This page
i18n Yes This page
instanceScope Yes This page
attachments Yes This page
composerPreferences No This page
mediaViewer No Image viewer
conversations No, throws when missing This page
groupManagement No, throws when missing This page
memberStore No This page
workItems No, throws when missing This page
mentions No This page
cards No Interactive cards
profileCard No Profile card
agentConfig No This page
agentGroupPolicy No This page
conversationResources No This page
messageSearch No This page
agentRuntime No This page
navigation No This page
workReferences No This page
forward No This page
agentActivity No Read-only progress (experimental · transitional): the live run table of Agent runs, always present on a Chat SDK host; see Chat SDK host. Replaced when the planned Agent runs capability lands
agentRuns Planned No Agent runs: stopping a run and loading runs and their events; see @openmaxai/chat

createLocalPorts provides default drafts, attachments, render, attention, i18n and instanceScope; see Custom backend. You only need the tables below member by member when you implement one yourself.

What to do on errors

  • Fail by rejecting. An async member that fails returns a rejected Promise (throws). The UI decides per member whether to roll back and notify, give up silently, or keep the item for a retry; each table says which under "Behavior and errors". Notifications go through attention.notify("error", …); see Errors and expired sessions.
  • "None" is not an error. Members documented as returning undefined or an empty array when nothing is found do so for missing, deleted or inaccessible items, without throwing: the UI relies on it to tell "none" from "failed".
  • When the server explicitly refuses (for example the recall window has passed), recallMessage and editMessage (and addReaction, removeReaction) throw ChatOperationNotAllowedError, or any object with chatOperationNotAllowed: true. For recall and edit the UI then says "cannot recall / cannot edit" instead of "failed, retry"; reactions do not single out refusals: a refusal rolls back like any other failure and shows "reaction failed / removing the reaction failed".
  • On a host built by createChatHost({ adapter }), every error the components receive is a ChatSdkError: one with kind forbidden also carries chatOperationNotAllowed: true, and the rest are shown or kept silent by kind, following the rules in this section; see Error model. Planned
  • Send errors are shown to the user. The message of the Error thrown by sendMessage becomes the notification text as-is; without a message, a generic text is shown. Write it for people.
  • Card actions do not throw; they return a result with a kind. See Interactive cards · Errors.
  • Synchronous members must not throw. Members such as currentUserId, getMember, previews and t are called during render; throwing makes the whole component throw.

identity

Type ChatIdentityPort. The current user, member lookup, directory search.

Member Signature Required Behavior and errors
currentUserId () => string Yes Member id of the current user. Read synchronously; returns "" before the data arrives, in which case your own messages look like someone else's. Once it arrives, pass a new host object
getMember (memberId: string) => ChatParticipant | undefined Yes Member by id, synchronous. Returns undefined when not found; the UI does not fetch it for you
listMembers (conversationId: string) => readonly ChatParticipant[] Yes Members of a conversation, synchronous; used for @ candidates. Paging and caching are the host's
searchDirectory (input: { search: string; cursor?: string }) => Promise<ChatDirectoryPage> Yes Searches the organization directory (not conversation members): picking people to message, to create a group with or to add, and organization members among @ candidates. Rejects on failure; @ candidates then show conversation members only, without a notification

messaging

Type ChatMessagingPort. Each optional member switches on one feature; without it only that feature is missing. See Capabilities · Optional capabilities.

Member Signature Required Behavior and errors
sendMessage (input: SendMessageInput) => Promise<void | ChatSendOutcome> Yes Sends a message. Returns { blocked } when the content filter stops it, instead of throwing. Rejects on failure: the message stays in place marked "Send failed", with retry and delete, and the error's message is shown. When the input carries clientMessageId, use it as the backend's deduplication key and return it as client_msg_id on messages read back: that keeps a retry from creating a second message, and keeps the row from remounting when the send is confirmed
loadThread (conversationId: string, cursor?: string, options?: ChatThreadLoadOptions) => Promise<ChatThreadPage> Yes Without cursor, the latest page; with it, older pages; with options.direction: "newer", cursor is a newerCursor and the page goes newer. Without cursor and with options.aroundSeq (a seq above 0), a window around that message, with nextCursor / newerCursor when there is more on either side. A host that ignores aroundSeq returns the latest page: opening a conversation does not land on the first unread, and jumping to a message outside the window says the jump is unavailable. options.limit is an upper bound on how many messages the page should hold, given only when paging newer and for the latest page (the new message area asks for 100 when paging newer by cursor, not for the two pages it adds right after opening); you may ignore it or return fewer (for example at the server's cap), and the package tells whether there is more only from the returned newerCursor / nextCursor, never from the count. Messages in ascending seq order. Reject when it cannot load instead of returning an empty page: an empty page without nextCursor reads as "no older messages"
createConversation (input: CreateConversationInput) => Promise<{ conversationId: string }> Yes Creates a conversation and returns only its id. The host decides the conversation kind. Rejects on failure; the UI shows "Failed to open conversation"
loadThreadSince (conversationId: string, afterSeq: number) => Promise<readonly ChatMessage[] | ChatThreadSincePage> No Messages with seq greater than afterSeq, ascending. Return either an array or { messages, hasNewer }. With an array, [] means nothing new and the UI only stops on [], so new messages cost at least one extra request; with hasNewer: false the UI stops right after merging the batch. Take hasNewer from the server, not from the batch size. May return only part of them; the UI keeps asking, up to a limit, so do not loop in the host. Rejects on failure; the UI gives up silently and tries again on the next signal
loadMessage (conversationId: string, messageId: string) => Promise<ChatMessage | undefined> No One message by id (quote bars, image captions, and the new text after a messageChanged for someone else's edit). Returns undefined for recalled, deleted or inaccessible messages instead of throwing
addReaction (messageId: string, code: string) => Promise<void | ChatMessageChangeResult> No Adds a reaction. Takes effect only together with removeReaction. The UI shows it optimistically; on rejection it rolls back and notifies. Never called concurrently for the same message and emoji
removeReaction (messageId: string, code: string) => Promise<void | ChatMessageChangeResult> No Removes one of the user's reactions; errors as above
recallMessage (messageId: string) => Promise<void | ChatMessageChangeResult> No Recalls the user's own message. The UI shows the recall optimistically; on rejection it rolls back and notifies; throw ChatOperationNotAllowedError when it is not allowed. On success deleted_at must really land on the message, or the next load brings it back
editMessage (messageId: string, edit: ChatMessageEditInput) => Promise<void | ChatMessageChangeResult> No Edits the user's own message; attachments are replaced as a whole set. Failure and refusal as for recallMessage; the edit box stays open with the user's text in it, ready to retry. On success the new body must land on the message with content_version increased by one
listMessageEdits (messageId: string) => Promise<readonly ChatMessageEdit[]> No Revision history in ascending time order. Fetched when "(edited)" is clicked
loadChangesSince (conversationId: string, sinceChangeSeq: number) => Promise<ChatThreadChangesPage> No One page of the change log with numbers above sinceChangeSeq (0 means from the first change), ascending. Takes effect only together with getMessagesByIds; see Change log below. Returns one page per call; the UI follows nextSinceChangeSeq and hasMore itself, so do not loop in the host. Rejects on failure; the UI gives up silently and tries again on the next catch-up
getMessagesByIds (conversationId: string, messageIds: readonly string[]) => Promise<ChatThreadMessagesByIdsPage> No The current version of a batch of messages by id; a recalled one comes back as its tombstone. At most 100 distinct ids per call. Ids that no longer exist go in missingIds (the UI removes them), ids not returned this time and to be asked again go in deferredIds. Fails as loadChangesSince
loadReadCursors (conversationId: string) => Promise<ChatReadCursorSnapshot> No Read snapshot, fetched once when a conversation opens; the read and delivery signals move it on. Reject when it cannot load rather than inventing one; the UI then silently shows no receipts
sendTyping Planned (conversationId: string, active: boolean) => Promise<void> No Tells the others in the conversation "I am typing" or "I stopped"; the composer calls it on the rhythm in Sending typing. Failures are silent: no notice, no retry. Without it, others never see you typing
pinMessage Planned (messageId: string) => Promise<void> No Pins a message. Takes effect only together with unpinMessage. Shown optimistically; on failure reject: rolled back with a notice; throw ChatOperationNotAllowedError when not allowed. On success pinned_at and pinned_by must land on the message
unpinMessage Planned (messageId: string) => Promise<void> No Unpins; errors as above

Change result: on success addReaction, removeReaction, recallMessage and editMessage may return a ChatMessageChangeResult, or void as before.

Field Type Meaning
changeSeq number The number of this change in the conversation's change log; 0 means nothing changed (a repeated reaction, or a recall that another recall or delete beat). When the conversation has a change watermark (a window came with headChangeSeq), the chat uses it to recognise the push for this change that arrives later; without a watermark it has no effect
editedAt string When the server recorded the edit (ISO string); edits only

With void the UI still waits for the push, or for the next time the message is fetched, to settle the change.

Change log: loadThreadSince only fetches messages with a greater seq, so changes others made to existing messages (edits, recalls, deletes, reactions, card settlements) while you were away or disconnected are not fetched by it. When the host provides loadChangesSince and getMessagesByIds and its windows carry headChangeSeq, every catch-up (opening or switching back to a conversation, reconnecting) goes on, after the new messages, to catch up on changes from the change watermark; see Gap fill · Catching up on changes.

Field On Meaning
headChangeSeq ChatThreadPage, ChatThreadSincePage The latest change-log number, read in the same snapshot as the page (head_change_seq on the server's list response); the change watermark starts from it. Pages paged older or newer carry it too. Leave it out when you don't have it rather than making up 0: without it the conversation does not catch up on changes
changes ChatThreadChangesPage An array of ChatThreadChange (changeSeq, messageId, messageSeq), ascending by number; empty when tooOld
nextSinceChangeSeq, hasMore ChatThreadChangesPage Where the next page starts, and whether there is more
tooOld ChatThreadChangesPage The requested position can no longer be listed (past retention, or beyond the latest number): the UI refetches the latest window
messages, missingIds, deferredIds ChatThreadMessagesByIdsPage The messages found, ids that no longer exist, ids to ask for again

The body is Markdown Planned: text on SendMessageInput is Markdown source. Formatting added in the composer is all inside that one string; there is no split between title and body and no separate format marker. The host passes text to the backend as usual and declares no extra capability, and the composer does not hide the formatting buttons based on host capabilities; see Composer · Expanded editor. The bodies of received messages from people are drawn as Markdown too; see render.

drafts

Type ChatDraftsPort. Drafts per conversation; the composer writes them, the conversation list reads them.

Member Signature Required Behavior and errors
get (conversationId: string) => ChatComposerDraft | undefined Yes Reads a draft, to restore it when switching back or when the composer remounts. undefined when there is none
save (conversationId: string, draft: ChatComposerDraft) => void Yes Writes a draft. Whether an empty draft is deleted or kept is up to you
clear (conversationId: string) => void Yes Clears it after a successful send
previews () => Readonly<Record<string, string>> Yes Conversation id → the one-line draft preview shown in the list. Returning a new object each time is fine
subscribe (listener: () => void) => () => void Yes Calls listener when drafts change; returns an unsubscribe function. Extra calls do no harm

Keep drafts apart from instanceScope.storage: the list has to subscribe to draft changes.

inboundDelivery

Type ChatInboundDeliveryPort. The SDK owns the realtime connection: the host gives the connection parameters (the four required members below), and the SDK connects, authenticates, reconnects and turns server frames into signals for the components. Your app does not open a realtime connection of its own.

Member Signature Required Behavior and errors
endpointUrl () => string Yes Address the SDK connects to; "" when there is none, and then the SDK does not connect
authToken () => Promise<string | undefined> Yes Fetched by the SDK before every connection; undefined means no credentials right now, so no more reconnects
clientId () => string Yes Identifier of this device or client, sent by the SDK when it connects
isMock () => boolean Yes Whether this is demo mode. When true the SDK does not connect and signals come only from subscribe
subscribe (onSignal: (signal: ChatInboundSignal) => void) => () => void No Entry point for host-forwarded signals; returns an unsubscribe function. Transitional: while your app still holds its own connection during migration, turn that connection's frames into signals and forward them here, and the SDK does not open a second connection (two connections with the same device id overwrite each other's sync position). Drop it once your app no longer has its own connection. A demo host (isMock() is true) also pushes signals here. Signal kinds and fields: Realtime and sync · Realtime signals

Signal rules: messages only says "there are new messages" and carries no body; reaction carries all four fields because a reaction changes an existing message; messageChanged names the message and the kind of change (edited / recalled / deleted) but carries no body; both carry changeSeq when the frame has a change number, and leave it out otherwise; send reconnected once per real reconnect, not on every heartbeat; optionally send connected once on the connection's first successful open (the list and open conversations catch up once; nothing is reset). A host that forwards signals also forwards disconnected when its connection drops and typing when someone else's typing state arrives; the planned connection status bar and the typing indicator rely on them. Planned

render

Type ChatRenderPort. The host renders message bodies and images.

Member Signature Required Behavior and errors
renderMessageText (text: string, ctx: { message: ChatMessage }) => ReactNode Yes The body of a text message, media captions, system notices. You draw links, @mentions and work item references; a mention element needs data-mention-name (plus data-mention-id when known, and data-mention-type for @all) so that pasting it back into the composer still works. The body of a text message is Markdown and must be drawn as Markdown, with mentions and links handled as above Planned
renderMarkdown (source: string, ctx?: { message: ChatMessage }) => ReactNode Yes Agent replies. Use ctx.message.mentions to tell whether the current user is mentioned

Both members draw by the same Markdown rules — which syntax is supported, how links and HTML are handled, and what happens to mentions and code: Message thread · Markdown body. Planned | renderImage | (props: { src: string; alt?: string; onError?: () => void }) => ReactNode | Yes | Images in messages. Wire onError to <img onError>: the UI uses it to refresh an expired signed URL, so do not retry yourself | | renderRichText | (text: string) => ReactNode | Yes | Text with no message attached, such as a group description | | renderMention | (mention: { memberId: string; name: string }) => ReactNode | No | A single member @mention outside message text, such as the "@A to answer" line on a choice card. Draw it with the same style and data-mention-* attributes as mentions in message text; without it the UI draws plain blue text |

render members are called during render and must not throw.

renderStructuredMessage and renderCustomMessage are removed; their type is never, so setting them does not compile. To draw a kind of message yourself, write a message-display plugin; see Migrating.

attention

Type ChatAttentionPort.

Member Signature Required Behavior and errors
notify (level: "info" | "success" | "error", message: string) => void Yes Shows a notification. message is text for the user
setUnreadSignal (count: number) => void Yes Called when the total unread count across all conversations changes; count leaves out muted conversations and conversations the user only observes. Show it as a title badge, an icon, or not at all

i18n

Type ChatI18nPort.

Member Signature Required Behavior and errors
t (key: string, vars?: Record<string, string | number>) => string Yes Returns one string, with vars filled into its placeholders. See Internationalization
locale () => string Yes Current language, such as "zh-CN"; time formats follow it

instanceScope

Type ChatInstanceScopePort. Keeps several chat instances on one page apart.

Member Signature Required Behavior and errors
queryKeyScope () => string Yes Namespace of this instance; the chat keeps its request results apart by it
invalidate (scope: "conversations" | "messages" | "members") => void Yes Tells the host to refetch that kind of data. The chat calls it after sending, recalling, editing, pinning, hiding and opening a new conversation
storage { get(key: string): string | null; set(key: string, value: string): void; remove(key: string): void } Yes Key-value storage kept apart per instance (such as the last opened conversation, a client id). localStorage works, or memory only

attachments

Type ChatAttachmentsPort. Uploads and received attachments. With createLocalPorts you only pass an upload function; see Custom backend · Uploads.

Member Signature Required Behavior and errors
limits () => { maxAttachments: number; maxFileSizeBytes: number } Yes Most attachments per message and largest file size. maxAttachments of 0 hides the attachment button
start (files: readonly File[], hooks?: { onTasks?(taskIds: readonly string[]): void }) => Promise<readonly string[]> Yes Uploads and returns attachment ids, one per file in the order of files (when editing, that order is the display order). Call hooks.onTasks synchronously with the task ids before returning the Promise; skip it if you have no task ids. Rejects on failure: the message is marked "Send failed" and the error's message is shown
cancel (taskId: string) => void Yes The user cancelled the upload; the whole message is removed. Does nothing for a finished task; do not throw
getTask (taskId: string) => ChatUploadTask | undefined Yes Current progress of a task. undefined when there is no such task. Must return the same object while the task has not changed, or the component re-renders forever
subscribeTasks (listener: () => void) => () => void No Calls listener when any task changes. Without it there is no progress bar and no cancel button
resolveUrls (artifactIds: readonly string[]) => Promise<Readonly<Record<string, string>>> No Turns attachment ids (without the artifact:// prefix) into URLs usable right now, in one batch. Leave out ids that could not be resolved rather than giving an empty string; those attachments show as unavailable. Without it every received attachment shows as unavailable
resolveDownloadUrl (artifactId: string) => Promise<string | undefined> No Called when the user clicks a file's download button: turns one attachment id (without the artifact:// prefix) into a URL for downloading it right now. The URL from resolveUrls was resolved when the message was drawn and may have expired by then. Resolve undefined when it cannot be resolved; reject on transport failure. Either way the file row shows "Download failed" and the button becomes a retry. Without it the download button opens the URL from resolveUrls

composerPreferences

Type ChatComposerPreferencesPort.

Member Signature Required Behavior and errors
sendShortcut () => ChatSendShortcut Yes "enter": Enter sends; "mod-enter": Ctrl (Cmd on a Mac) + Enter sends. A changed setting takes effect at once

Without this capability, "enter" applies.

conversations

Type ChatConversationsPort. Required when rendering ConversationList.

Member Signature Required Behavior and errors
list (input: { search?: string; includeHidden?: boolean; cursor?: string }) => Promise<ChatConversationPage> Yes One page of conversations. An empty search means the default list; includeHidden includes hidden ones. Rejects on failure
setPinned (conversationId: string, pinned: boolean) => Promise<void> Yes Pins or unpins. The list refetches on success. Rejects on failure: the list stays as it was and a "Failed to pin conversation" or "Failed to unpin conversation" notice is shown
setHidden (conversationId: string, hidden: boolean) => Promise<void> Yes Hides or unhides. The list refetches on success. Rejects on failure: the list stays as it was and a "Failed to hide conversation" or "Failed to unhide conversation" notice is shown; a hidden conversation picked from search results is not opened when unhiding fails
setMuted (conversationId: string, muted: boolean) => Promise<void> No Mutes or unmutes (only notifications change; messages and unread counts work as before). The list refetches right away on success and the conversation's muted follows. Rejects on failure: the list stays as it was and the conversation list or ConversationHeader shows a "Could not mute the conversation" or "Could not unmute the conversation" notice. Not called for observed conversations. Without it the header has no mute toggle and the conversation list's rows and pinned grid offer no mute action
markReadUntil (conversationId: string, readUntilSeq: number) => Promise<void> No Moves the current user's read position in this conversation up to readUntilSeq (inclusive); the server only moves it forward. The message thread calls it with the last real message in view: never for an observed conversation, only with a larger seq per conversation, and again after a failure. The list refetches on success (unread clears). Rejects on failure with no notice. Without it the thread reports no read position and unread counts stay
loadConversation (conversationId: string) => Promise<(ChatConversation & { muted: boolean }) | undefined> No Loads one conversation by id, to open a conversation from a link when it is not in the loaded list. Returns undefined when it does not exist or cannot be accessed, without throwing; rejects on other failures. Without it such conversations cannot be opened; see Adapter interface · conversations. muted is required and must be the current user's own mute state for this conversation
loadUnreadTotal Planned () => Promise<{ count: number; mentions: number }> No The total unread count computed by the backend, not counting muted conversations or conversations the user only observes. Without it the total is added up from the fetched conversations, and is only a lower bound until the conversation list has been paged to the end

Pinned, hidden and muted state is read from the conversation's pinned, done and muted; see Data model · ChatConversation.

groupManagement

Type ChatGroupManagementPort. Required when rendering CreateGroupModal or ChatInfoPanel. Adding members, removing members, leaving and dissolving are optional members: the UI offers a button only for the ones present; a missing one means no button, so do not give a stub that throws when called. A host built by createChatHost has it only when the adapter has groupManagement, and after a successful write the SDK refreshes the conversation list or member list. The four optional members fail under the same convention as createGroup: throw a ChatSdkError; the UI shows its message, the package's text for the kind when that is empty, and the operation's own fallback sentence otherwise.

Member Signature Required Behavior and errors
createGroup (input: ChatCreateGroupInput) => Promise<{ conversationId: string }> Yes Creates a group and returns the new conversation id. Do not use messaging.createConversation instead. When the request fails, throw a ChatSdkError: the dialog stays open and shows its message; with an empty message it shows the package's text for the kind (such as "You don't have permission to do this."), or "Failed to create group. Please try again." for kinds without one. Any other thrown value is treated as a code error: it is logged with console.error and rethrown
updateGroupProfile (conversationId: string, updates: ChatGroupProfileUpdate) => Promise<void> Yes Changes the group name or description, one at a time. Rejects on failure; the UI says the save failed
addMembers (conversationId: string, memberIds: readonly string[]) => Promise<ChatGroupMembersChangeResult> No Adds people to the group. Judged per person: partial success still resolves, and those who failed are in failed with a kind and reason; rejects only when the whole request failed. Without it the group info panel has no "Add members"
removeMembers (conversationId: string, memberIds: readonly string[]) => Promise<ChatGroupMembersChangeResult> No Removes people from the group (usually owner only). Result and errors as addMembers. Without it there is no "Remove members"
leave (conversationId: string, options?: ChatGroupLeaveOptions) => Promise<ChatGroupLeaveResult> No The current user leaves. The owner may pass a successor newOwnerId; otherwise the server picks a human member, and dissolves the group when only Agents remain; which branch ran is in ChatGroupLeaveResult. Rejects on failure. Without it there is no "Leave group"
dissolve (conversationId: string) => Promise<void> No Dissolves the group (usually owner only). Rejects on failure. Without it there is no "Dissolve group"

memberStore

Type ChatMemberStoreReader (getMembers and subscribe of the @openmaxai/chat-store member store ChatMemberStore). The group info panel and the message thread read each member's conversation role from it and draw their buttons with can(). Optional; without it every role counts as unknown and the fallback rule applies. A host from createChatHost has it (the read side of its own member data).

Member Signature Required Behavior and errors
getMembers (conversationId: string) => readonly ChatMembership[] | undefined Yes The conversation's member list; each row carries the conversation role role. Returns undefined before the list has been loaded (roles unknown) and an empty array when it was loaded with no one in it. Returns the same object while nothing changed
subscribe (conversationId: string, listener: () => void) => () => void Yes Calls listener when the conversation's member list changes; returns an unsubscribe function

workItems

Type ChatWorkItemsPort. # work item references in the composer. Optional; without it the # plugin that needs it is not installed; see Composer plugins.

Member Signature Required Behavior and errors
search (input: { search: string; projectId?: string; cursor?: string }) => Promise<ChatWorkItemPage> Yes Searches projects and issues by text, in one list told apart by kind. An empty search returns a default page. With projectId, returns only that project's issues (used when expanding a project), and their projectId must be it

subConversations

Type ChatSubConversationsPort. Context sub-conversations: a conversation under a direct conversation or group for one context, with its own history, unread count and realtime, and the parent's members. Optional; without it no sub-conversation UI is drawn (the conversation list draws no dot for has_unread_subconversations).

Member Signature Required Behavior and errors
findOrCreate (input: ChatSubConversationFindOrCreateInput) => Promise<ChatSubConversationResult> Yes Finds the sub-conversation for input.context.key under input.parentConversationId, or under the direct conversation with input.peerMemberId, creating it when there is none. Idempotent. Resolves the sub-conversation (never its parent) and whether it was created; an archived match is returned as is. owner is deprecated: the owner comes from the credential. Rejects with a ChatSdkError-shaped error, message a sentence for the user when the backend code is known

mentions

Type ChatMentionsPort. The "@me" jump in the message thread.

Member Signature Required Behavior and errors
listUnread (conversationId: string) => Promise<ChatUnreadMentionsPage> Yes Unread mentions in this conversation. mentions may be one page; totalMe and totalAll are totals. Rejects on failure; no jump button is shown
markRead (conversationId: string, messageIds: readonly string[]) => Promise<void> Yes Marks mentions read after jumping to them. Failures are silent
markAllRead (conversationId: string) => Promise<void> Yes Marks all read, across all pages, not just the fetched one. Rejects on failure; the counts come back

agentConfig

Type ChatAgentConfigPort. The agent model picker in the DM header.

Member Signature Required Behavior and errors
loadModelState (agentMemberId: string) => Promise<ChatAgentModelState | undefined> Yes The agent's current model settings. Returns undefined without permission or for a non-agent instead of throwing; the control is then disabled
setModel (agentMemberId: string, model: string) => Promise<void> Yes Switches model; model is a ChatAgentModelOption.key. Returning does not mean it applied: the UI keeps polling loadModelState until applyState is no longer applying. Rejects on failure; the UI notifies
setModelVisibility (agentMemberId: string, visible: boolean) => Promise<void> Yes Whether the model name is shown to others. Rejects on failure; the UI notifies

agentGroupPolicy

Type ChatAgentGroupPolicyPort (@experimental). How agents reply in groups: read the policy, who may change it, change an agent's reply mode in one group, change its group allowlist. The policy and the allowlist belong to the agent (across groups); only the reply mode is per group. Used by the "Agent group settings" section of ChatInfoPanel; without it that section is not drawn.

Member Signature Required Behavior and errors
loadGroupPolicy (agentMemberId: string, options?: { fresh?: boolean }) => Promise<ChatAgentGroupPolicy | undefined> Yes The agent's group policy (group part only). Returns undefined when it cannot be read instead of throwing. fresh: true bypasses caches and reads from the server: use it as the base when reading and then changing the allowlist
canManageGroupPolicy (agentMemberId: string) => Promise<boolean | undefined> Yes Whether the current user may change this agent's group policy. false means definitely not (a read-only row); returns undefined when it cannot tell (current user unknown, ownership unavailable) and the panel skips that agent's row. The server still decides
setGroupReplyMode (input: { agentMemberId, conversationId, mode: ChatAgentGroupReplyMode }, options?: { signal?: AbortSignal }) => Promise<ChatAgentPolicyApplyOutcome> Yes Changes the agent's reply mode in one group. Resolves once the agent confirms; refused, offline and unconfirmed come back as outcomes, not throws
setGroupAllowlist (input: { agentMemberId, conversationIds: readonly string[] }, options?: { signal?: AbortSignal }) => Promise<ChatAgentPolicyApplyOutcome> Yes Sets the group allowlist to conversationIds (the full list; [] clears it). Outcomes as above
openAgentSettings (agentMemberId: string) => void No Opens the agent's settings page (where the group scope is changed). Without it the panel has no "Go to agent settings" link

None of the four required methods should reject: return undefined when nothing can be read or decided, and resolve every write with an outcome. If one rejects anyway, the panel treats it as unreadable / undecided, or reports the write as failed. Whatever the outcome (including aborted), the next loadGroupPolicy must read the server's value; aborted only stops waiting and does not undo a submitted write.

conversationResources

Type ChatConversationResourcesPort (@experimental). A conversation's images, files and links, newest first, paged by cursor. Optional; without it the UI that lists them is not drawn.

Member Signature Required Behavior and errors
list (query: ChatConversationResourcesQuery, options?: { signal?: AbortSignal }) => Promise<ChatConversationResourcePage> Yes One page of rows (ChatConversationResource: kind image / file with artifactId, fileName, contentType, sizeBytes; kind link with url, host, title; all with id, messageId, messageSeq, senderId, messageAt). query filters by kinds, senderId, since / until and free text, and pages by cursor / limit. Only rows of messages the caller can see now: recalled and deleted messages give none, edited ones what their current version holds. image / file rows always carry artifactId (resolve it with attachments.resolveUrls / resolveDownloadUrl). nextCursor absent on the last page. Rejects on failure; an empty conversation is an empty page

messageSearch

Type ChatMessageSearchPort (@experimental). Searching one conversation's messages. Optional; without it the UI that searches messages is not drawn.

Member Signature Required Behavior and errors
search (query: ChatMessageSearchQuery, options?: { signal?: AbortSignal }) => Promise<ChatMessageSearchPage> Yes One page of hits (ChatMessageSearchHit: messageId, conversationId, seq, senderId, createdAt, and snippet, plain-text parts with match: true on the matches; render them as text). Hits MUST be messages the caller can see now: recalled and deleted messages are never hits and their old text never appears in a snippet. Hits MUST be based on the current message text: a result that only matches pre-edit text is not returned, and snippets are built from the current text; edited messages stay searchable by their current text. Pages may be short or empty while nextCursor is present; keep paging by it. A blank query is an empty page. Rejects on failure; no hits is an empty page

A hit can be recalled after it was returned: a host that jumps to one handles a message that is no longer there.

agentRuntime

Type ChatAgentRuntimePort (@experimental). Managing the agent on the other side of a DM from the conversation info sidebar: the management area on the agent's identity card (pause / resume, interrupt, restart, a collapsible run status). Which actions there are, to whom, and how each runs are the host's answer; the package does not copy the permission rules or the agent's lifecycle. Without it there is no management area.

Member Signature Required Behavior and errors
loadState (agentMemberId: string) => Promise<ChatAgentRuntimeState | null> Yes null ⇒ the current user does not manage this agent: no management area at all (no "Agent settings" either). Otherwise { actions, status? }: actions in display order, each { action, enabled } (enabled: false draws it disabled; leave out what the user may never use), status the run status rows { label, value } as finished text. Rejects on failure; the area shows an error with "Retry", the rest of the sidebar is unaffected
runAction (agentMemberId: string, action: ChatAgentRuntimeAction, ui: ChatAgentRuntimeActionUi) => Promise<void> Yes action is "pause" | "resume" | "interrupt" | "restart". The host runs the whole flow (confirm, request, notice; the package shows none) and resolves when it is over, done, cancelled or failed alike; the package then calls loadState again. Draw the confirmation with ui.render(node): the package mounts it next to the management area the action came from (inside the same React tree), so from a floating window it opens inside that window; a later call replaces it, null removes it, and it is removed when runAction settles or the area goes away

Type ChatNavigationPort. In-app navigation; the chat components do not read it.

Member Signature Required Behavior and errors
navigate (href: string) => void Yes Goes to href
resolveHref (href: string) => string Yes Turns href into a value for <a href>

workReferences

Type ChatWorkReferencesPort. Where work references in message text ([#label](proj://…) / issue://…) point and how they open; the chat components do not read it. Message rendering uses it: pass it to workReferences of ChatMarkdown (or to links of ChatWorkReferenceChip in your own renderMessageText); the SDK default render wires it from ports.workReferences. When the rendering layer does not get it, references are still drawn as chips but are not clickable.

Member Signature Required Behavior and errors
href (ref: ChatWorkReference) => string | undefined Yes The browser URL put on <a href> (with basePath), used by middle click, new tab and copy link. Synchronous, no requests. Returning undefined keeps the chip clickable, just without a URL
open (ref: ChatWorkReference) => Promise<"ok" | "denied" | "missing" | "failed"> Yes Called on a plain left click: reads the item with the current user's permissions and navigates. A click while the previous call has not returned is ignored. When it is not "ok" (a throw counts as "failed"), a rendering layer wrapped with bindWorkReferenceNotice shows attention.notify("error", …)

forward

Type ChatForwardPort (@experimental). Forwarding messages into other conversations. Optional: without it, or without conversations (the picker lists its candidates from the first page of conversations.list), messages have no "Forward" button. Today MessageThread and MessageThreadNext (the SDK's CwsMessageThread) offer it on one message at a time and call forwardMessages; mergeForwardMessages has no entry point in the components yet. A host built by createChatHost of @openmaxai/chat-sdk gets it from the adapter's forward.

Member Signature Required Behavior and errors
forwardMessages (sourceConversationId: string, body: ForwardRequestBody) => Promise<ForwardResponseData<ForwardTargetResult>> Yes Copies each message in body.message_ids into each target, as POST /conversations/{sourceConversationId}/messages/forward does. Send body as given: each target carries its own client_msg_id, created when the user first submits and reused unchanged when they retry, so a retry is a replay on the server. Resolve with one result per target, in request order, even when every target failed; the dialog lists failed targets one by one. Reject only when the request as a whole fails; the dialog then says forwarding failed and offers a retry with the same body. When the server refused the request itself (a note over the size limit, a recalled source), throw ChatOperationNotAllowedError (or any object with chatOperationNotAllowed: true): resending the same body cannot succeed, so the dialog says it cannot forward and offers no retry
mergeForwardMessages (sourceConversationId: string, body: ForwardRequestBody) => Promise<ForwardResponseData<MergeForwardTargetResult>> Yes Same, but sends one chat history message (CHAT_HISTORY) per target