OpenMax
Free Trial

Capabilities

Every capability on the host — which are required, what each optional one switches on, what happens without it, and what the SDK provides for you.

Capabilities

Each capability is a field on the host (the ChatHost object), typed as a …Port interface (ChatMessagingPort, ChatMediaViewerPort, …). Components call it whenever they need to send a message, look up a member or open an image.

src/chat-host.tsx

import type { ChatHost } from "@openmaxai/chat/host";
import { ChatProvider } from "@openmaxai/chat-sdk/react";

const host: ChatHost = {
  identity: { currentUserId: () => "me", getMember, listMembers, searchDirectory },
  messaging: { sendMessage, loadThread, createConversation },
  // ...the other required capabilities, plus any optional ones
};

<ChatProvider host={host}>{/* chat components */}</ChatProvider>;

For OpenMax, createChatHost(config) returns a complete host. Write one by hand only for a mock, a test, or another backend.

Required capabilities

The ChatHost type does not allow leaving these out.

Field Purpose
identity Current user id, member lookup, directory search
messaging Send, load thread pages, create a conversation; optional methods enable reactions, recall, edit, read receipts
inboundDelivery Realtime delivery: the endpoint, token and client id the SDK connects with, plus subscribe, the transitional entry point for host-forwarded signals
drafts Per-conversation drafts
render Message text and image rendering
attention Toasts and the unread signal
i18n t() and locale()
instanceScope Query-key namespace, cache invalidation, scoped key–value storage
attachments Upload task board, limits, cancel, attachment URL lookup

That is nine; every other field is optional. If you render ConversationList or the group management components, type your host as ChatHostWithConversationList or ChatHostWithGroupManagement: they make conversations and groupManagement required, so leaving one out fails to compile instead of throwing at runtime. For both, write ChatHostWithConversationList & ChatHostWithGroupManagement.

Optional capabilities

Leaving one out has one of three effects: usually its feature is absent while the rest keeps working; a few show a disabled placeholder; and without conversations or groupManagement the component that needs it throws. See When an optional capability is missing. Uncheck boxes to try it:

capability-toggles demo

Screenshot of this demo. It runs on an in-memory sample host (useDemoHost from the demo kit, which is not part of the packages); in your app, pass the host from createChatHost() instead.

Demo source (uses the docs demo kit and Tailwind CSS classes, so it cannot be copied as is): capability-toggles.tsx
"use client";

import { CreateGroupModal } from "@openmaxai/chat/group-management";
import { ChatHeader } from "@openmaxai/chat/header";
import { MessageThread } from "@openmaxai/chat/message-thread";
import { ChatProvider } from "@openmaxai/chat-sdk/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useState } from "react";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import {
	AGENT,
	Button,
	OPTIONAL_CAPABILITIES,
	type OptionalCapability,
	useDemoData,
	useDemoHost,
	useIsCompact,
} from "./kit";

export default function CapabilityToggles() {
	const { conversations, lang } = useDemoData();
	const isCompact = useIsCompact();
	const [off, setOff] = useState<OptionalCapability[]>([]);
	const [conversationId, setConversationId] = useState("launch");
	const [creating, setCreating] = useState(false);
	// The legacy MessageThread reads react-query and the host brings none: wrap a QueryClientProvider
	// yourself.
	const [queryClient] = useState(() => new QueryClient());

	const host = useDemoHost({ without: off });
	const conversation =
		conversations.find((c) => c.id === conversationId) ?? conversations[0];
	const isAgentDm = conversation.id === "helper";

	const toggle = (name: OptionalCapability) =>
		setOff((list) =>
			list.includes(name) ? list.filter((n) => n !== name) : [...list, name],
		);

	return (
		<div
			className={`flex h-full bg-background text-foreground ${isCompact ? "flex-col" : ""}`}
		>
			<fieldset
				className={`shrink-0 overflow-auto p-3 text-sm ${
					isCompact
						? "flex flex-wrap gap-x-3 gap-y-1 border-b"
						: "w-48 space-y-1.5 border-r"
				}`}
			>
				<legend className="sr-only">Capabilities</legend>
				{OPTIONAL_CAPABILITIES.map((name) => (
					<label
						key={name}
						className="flex items-center gap-2 font-mono text-xs"
					>
						<input
							type="checkbox"
							data-capability={name}
							checked={!off.includes(name)}
							onChange={() => toggle(name)}
						/>
						{name}
					</label>
				))}
			</fieldset>

			<QueryClientProvider client={queryClient}>
				{/* Re-mount the chat whenever the host changes. ChatProvider installs only the
				    composer plugins this host can serve: without `workItems` there is no `#`. */}
				<ChatProvider key={off.join(",")} host={host}>
					<main className="flex min-h-0 min-w-0 flex-1 flex-col">
						<div className="flex flex-wrap items-center gap-2 border-b px-3 py-2 text-xs">
							<select
								aria-label="conversation"
								className="rounded border bg-background px-2 py-1"
								value={conversationId}
								onChange={(e) => setConversationId(e.target.value)}
							>
								<option value="launch">{conversations[0].name}</option>
								<option value="helper">
									{lang === "zh" ? "我的 Agent" : "My agent"}
								</option>
							</select>
							{/* A module component throws if its capability is missing: leave it out instead. */}
							{host.groupManagement && (
								<Button
									size="xs"
									variant="outline"
									onClick={() => setCreating(true)}
								>
									{lang === "zh" ? "新建群聊" : "New group"}
								</Button>
							)}
						</div>
						<ChatHeader
							conversation={conversation}
							headerTitle={conversation.name ?? ""}
							headerSubtitle={null}
							isAgentCollab={false}
							isObserving={false}
							collabAgents={[]}
							typingText={null}
							mode={isCompact ? "compact" : "full"}
							infoPanelOpen={false}
							isAgentOwnerDm={isAgentDm}
							agentModelMemberId={isAgentDm ? AGENT : undefined}
						/>
						<MessageThread key={conversation.id} conversation={conversation} />
					</main>
					{host.groupManagement && (
						<CreateGroupModal
							open={creating}
							onClose={() => setCreating(false)}
						/>
					)}
				</ChatProvider>
			</QueryClientProvider>
		</div>
	);
}
Capability Switches on Without it
conversations ConversationList: list, pin, hide Throws an error naming the capability
groupManagement CreateGroupModal, ChatInfoPanel; the optional addMembers, removeMembers, leave, dissolve are the group info panel's writes for adding, removing, leaving and dissolving Both throw an error naming the capability. For each of the four optional writes that is missing, the panel will not draw that button (the panel reading them is not done yet; today it still calls its callback props, see Group management)
mentions "@me" jump capsule in the thread No capsule
workItems # work-item references in the composer No # trigger or toolbar button; see Composer plugins
profileCard Profile popover on avatars and the DM header Avatars are not clickable
cards Buttons and options on interactive cards (the card plugin needs it) The card plugin is not installed and cards are drawn read-only: body and result line show, business buttons do not, options and "Create agent" are disabled, truncated cards have no "expand"; no message is sent in place of an answer
agentConfig Agent model selector in the header (needs agentModelMemberId on ChatHeader) A disabled placeholder control
mediaViewer Click an image to open the viewer Images are not clickable
composerPreferences Configurable send shortcut Enter sends
navigation In-app navigation The chat components do not read it
workReferences Where work reference chips in message text point and how they open The chat components do not read it; when the message rendering layer does not get it, the chips are not clickable. See workReferences

Required capabilities also have optional methods that switch features on:

Optional method on Switches on Without it
messaging: reactions (add and remove both required) Reaction picker, toggleable reaction chips No picker; chips not clickable
messaging: recall, edit, edit history "Recall" and "Edit" in the message menu; "(edited)" opens the history None of these
messaging: read receipts DM ticks, group read count No receipts
messaging: load message by id Quotes of messages outside the loaded window; full media captions; the new text of someone else's edit appears live Quote stays empty; captions not completed; edits by others appear only when the messages load again (recalls and moderation removals stay live)
messaging: incremental fetch (loadThreadSince) New messages from others appear live They appear after the conversation reloads; reactions still update live
inboundDelivery: subscribe Host-forwarded live updates, while your app still has its own connection (transitional) The SDK's own connection delivers them; with no connection either (endpointUrl() returns "" or isMock() is true), no live messages, reactions, edits, recalls, receipts or card results
attachments: URL resolution Showing received attachments Attachments shown as unavailable
attachments: upload (limit above 0) Attachment button in the composer No attachment button
render: structured message rendering Your own drawing of structured messages Rendered as ordinary messages

Field names are in the @openmaxai/chat API reference; the members of each capability and their error rules are in Host capabilities.

Agent runs

Planned

The planned optional capability agentRuns switches on the agent run UI: run progress, tool steps and the stop button in the message thread, the run entry in the header, and the Agent panel.

Field Switches on Without it
agentRuns Run progress, run list, stop button No run progress; the agent's messages show as usual
agentRuns.loadAgentRuns The Agent panel No Agent panel

Run events also have to reach the host over the realtime connection; with agentRuns but no realtime events, run progress appears only from the snapshot when a conversation is opened. See Connect your own backend.

When an optional capability is missing

Behavior Capabilities
Hidden; the rest of the screen is unchanged mentions, profileCard, mediaViewer, the action footer of cards, optional messaging methods
Hidden: the composer plugin that needs it is not installed; the rest of the composer works workItems
Read-only drawing: the message-display plugin that needs it is not installed, and the message area draws those messages read-only, without throwing cards
Disabled placeholder; the layout does not shift agentConfig, the options and the "Create agent" button on a card
Error naming the missing field conversations (ConversationList), groupManagement (CreateGroupModal, ChatInfoPanel)

A message-display plugin whose capability is missing is skipped without throwing, also when @openmaxai/chat is used on its own. This differs from composer plugins (used with @openmaxai/chat alone, a composer plugin with a missing capability throws) on purpose: having no cards is a valid state that means read-only cards, not a forgotten capability.

The chat components have no error boundary, so an error unmounts the whole React tree and the page goes blank; see Known limitations. Module components throw rather than show an empty state, so a missing capability is not mistaken for "no conversations". To leave a module out, don't render its component; the group management entry points (createGroupAction on ConversationList, onToggleInfoPanel on ChatHeader) are props you simply don't pass. With the Chat SDK there is nothing to do: when the adapter has no groupManagement, the SDK's list, header and floating surfaces draw no group management entry, and CwsGroupInfoPanel draws nothing.

These props fail quietly when omitted:

Prop Component When you don't pass it
onVisibleSeqChange MessageThread Read position never advances; the conversation stays unread after a reload
createGroupAction ConversationList No "new group" button
onToggleInfoPanel ChatHeader No group info button
onLeave / onDelete / onRemoveMembers / onAddMembers ChatInfoPanel Confirm dialogs open, then nothing happens
memberStatus ChatInfoPanel Every member shows as offline

Composer plugins

Each composer plugin declares the capabilities it needs in requiredPorts; the # work-item plugin, for example, needs workItems. ChatProvider installs only the plugins whose capabilities the host has and skips the rest: without workItems the composer has no # trigger or toolbar button, while @ and everything else work as usual. You don't filter the plugin set yourself; without plugins you get the built-in plugins, and a list you pass is narrowed by the host's capabilities in the same way.

If the host changes at runtime (as in the demo), the plugins are picked again; the SDK compares plugins by id and keeps the list reference while the ids stay the same (swapping a plugin object under the same id has no effect), so plugins needs no module-scope constant or useMemo.

The capabilities each built-in plugin needs are in Built-in plugins; how your own plugin declares them is in Composer plugins · Required capabilities.

What the SDK provides

createLocalPorts(...) from @openmaxai/chat-sdk/react returns the backend-independent capabilities: drafts, attachments (upload task board; you supply the transport), render, attention, i18n and instanceScope. Add the backend ones yourself:

src/chat-host.tsx

import type { ChatHostWithConversationList } from "@openmaxai/chat/host";
import { createLocalPorts } from "@openmaxai/chat-sdk/react";

const host: ChatHostWithConversationList = {
  identity: myIdentity,
  messaging: myMessaging,
  inboundDelivery: myInbound,
  conversations: myConversations,
  ...createLocalPorts({
    scope: "my-chat",
    currentUserId: () => myId,
    attachments: { limits, upload, resolveUrls },
  }),
};

Defaults: render draws agent replies as Markdown and other text as plain text with line breaks, @mentions and http(s) links; attention does nothing. Anything in ports replaces the whole capability.

Install a hand-built host with ChatProvider too.

What the OpenMax host provides

createChatHost(config) uses the same local capabilities and adds identity, messaging (send, load, incremental fetch, create conversation, fetch one message by id, plus reactions, recall, edit and edit history), inboundDelivery (with wsUrl) and conversations for OpenMax; uploads work only inside ConversationScope. mediaViewer, composerPreferences, localRecords, navigation and workReferences can be passed through config.ports. The other optional capabilities come from the adapter's members of the same name (for example groupManagement, cards, mentions, workItems, agentConfig); see Adapter interface · ChatSdkAdapter.