@ai4b-team/fsaos-gateway-sdk 3.0.0 → 3.2.0

package/dist/index.d.cts

@@ -664,6 +664,33 @@ interface ChannelMessage {
     intent_card?: Record<string, unknown>;
     thread_summary?: Array<Record<string, unknown>>;
 }
+/** A parsed card item bundled with channel messages from the kernel v2 response. */
+interface ChannelCard {
+    id: string;
+    path: string;
+    name: string;
+    createdAt: string;
+    action: string;
+    targetId?: string;
+    targetPath: string;
+    targetDisplayName: string;
+    targetDescription: string;
+    targetItemType: string;
+    /** Derived tool use ID (name without 'card-' prefix). */
+    toolId?: string;
+    /** Path of the parent message (for child cards). Undefined for sibling cards. */
+    parentMessagePath?: string;
+    visibility: string;
+}
+/** Full response from fetchChannelMessagesWithCards — includes bundled cards. */
+interface ChannelMessagesResponse {
+    messages: ChannelMessage[];
+    /** Cards that are direct children of messages in this page. Keyed by message path. */
+    messageCards: Map<string, ChannelCard[]>;
+    /** Cards that are direct siblings (children of the channel itself). */
+    siblingCards: ChannelCard[];
+    mode: 'top_level' | 'thread';
+}
 /**
  * Fetch channel messages via the kernel's `get-channel-messages` method.
  *
@@ -676,9 +703,24 @@ interface ChannelMessage {
  *                         If omitted, returns top-level messages.
  */
 declare function fetchChannelMessages(channelPath: string, parentMessageId?: string): Promise<ChannelMessage[]>;
+/**
+ * Fetch channel messages WITH bundled cards from the kernel v2 response.
+ *
+ * The kernel's get-channel-messages (v2) returns messages interleaved with
+ * their associated cards (both sibling cards and child cards). This function
+ * parses both and groups child cards by their parent message path.
+ *
+ * This eliminates the N+1 query problem where the frontend previously made
+ * separate `list` calls for each message to fetch its cards.
+ */
+declare function fetchChannelMessagesWithCards(channelPath: string, parentMessageId?: string): Promise<ChannelMessagesResponse>;
 /** Response shape from fetchChannelMessagesPage. */
 interface ChannelMessagesPage {
     messages: ChannelMessage[];
+    /** Cards grouped by parent message path (child cards of messages in this page). */
+    messageCards: Map<string, ChannelCard[]>;
+    /** Cards that are direct siblings of the channel (not nested under a message). */
+    siblingCards: ChannelCard[];
     /** Mode returned by kernel: 'top_level' or 'thread'. */
     mode: 'top_level' | 'thread';
 }
@@ -1482,14 +1524,24 @@ interface ChannelMessagesOptions {
     realtime?: boolean;
     enabled?: boolean;
 }
-/** Fetch channel messages via the kernel's `get-channel-messages` method. */
+/**
+ * Fetch channel messages via the kernel's `get-channel-messages` method.
+ *
+ * Now uses `fetchChannelMessagesWithCards` to get bundled cards in a single
+ * request, eliminating the N+1 query problem. Cards are returned alongside
+ * messages, grouped by parent message path.
+ */
 declare function useChannelMessages(options: ChannelMessagesOptions): {
     messages: ChannelMessage[];
+    /** Cards grouped by parent message path (child cards of messages). */
+    messageCards: Map<string, ChannelCard[]>;
+    /** Cards that are direct siblings of the channel (not nested under a message). */
+    siblingCards: ChannelCard[];
     threads: ChannelMessage[];
     isLoading: boolean;
     isFetching: boolean;
     error: Error | null;
-    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<ChannelMessage[], Error>>;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<ChannelMessagesResponse, Error>>;
 };
 /** Options for useInfiniteChannelMessages. */
 interface InfiniteChannelMessagesOptions {
@@ -1523,6 +1575,10 @@ interface InfiniteChannelMessagesOptions {
  */
 declare function useInfiniteChannelMessages(options: InfiniteChannelMessagesOptions): {
     messages: ChannelMessage[];
+    /** Cards grouped by parent message path (child cards of messages). */
+    messageCards: Map<string, ChannelCard[]>;
+    /** Cards that are direct siblings of the channel (not nested under a message). */
+    siblingCards: ChannelCard[];
     threads: ChannelMessage[];
     isLoading: boolean;
     isFetching: boolean;
@@ -1875,4 +1931,4 @@ declare function uploadFile(file: File | Blob, options: UploadOptions, onProgres
  */
 declare function useFileUpload(): UseFileUploadReturn;
 
-export { type AccountInfo, type Channel, type ChannelMessage, type ChannelMessagesOptions, type ChannelMessagesPage, type ChannelsOptions, type ComponentOpener, ComponentRenderer, type CreateParams, type DeleteParams, EnforcementDeniedError, type EnforcementPayload, type FieldDescriptor, type FileRef, type GatewayParams, type GatewayResponse, type InfiniteChannelMessagesOptions, type ItemVersionsOptions, type ItemVersionsResult, type ItemsFilter, KernelProvider, type LinkParams, type MoveParams, type Notification, type NotificationsOptions, type OpenEnvelope, type OpenOptions, type PrincipalData, type ResolveParams, type ResolveResponse, type ResolveResultItem, type SessionEntry, type TypeDefinition, type TypeHelpers, type TypeSchema, type UnreadCountsOptions, type UpdateParams, type UploadItem, type UploadOptions, type UploadResult, type UseFileUploadReturn, type VFSEdge, type VFSItem, auth, awaitScopeReady, callTool, clearCachedToken, clearSession, createItem, disconnectSSE, disposeVfsRealtimeWs, emitEvent, fetchChannelMessages, fetchChannelMessagesPage, fetchEdgesForItem, fetchItemHistory, fetchItemVersions, fetchItems, fetchMemberFocus, fetchOpenEnvelope, fetchRecentActivity, fetchTypeDefinitions, fetchVfsChildren, fetchVfsChildrenPage, fetchVfsItem, fetchVfsItemById, fetchVfsTree, gatewayCall, getAccessToken, getAssetUrl, getDefaultSort, getRequiredFormFields, getScope, getScopeVersion, getSessionEntry, initSession, initVfsRealtimeWs, interpretSchema, invalidateAllVfs, invalidateChannelMessages, invalidateChildren, invalidateItem, invalidateOpenEnvelope, invalidatePathAndParent, invalidateSubtree, invalidateTypes, isScopeReady, listChildren, mount, mountRealtimeScope, normalizeItem, ping, pushChanges, queryClient, readItem, registerCleanup, resetAllSdkState, resolvePrincipalId, setCachedToken, setScope, setupRequireShim, signal, subscribeScope, subscribeToEvents, subscribeToPath, subscribeToScope, unmountRealtimeScope, updateItem, uploadFile, useAccounts, useAllChannels, useAsset, useAuth, useChannelMessages, useChannels, useChildren, useComponent, useCreate, useDelete, useDmChannels, useEdges, useEventStream, useFileUpload, useInfiniteChannelMessages, useInfiniteChildren, useInfiniteItems, useItem, useItemById, useItemHistory, useItemVersions, useItems, useLink, useList, useMemberFocus, useMove, useMutation, useNotifications, useOpen, usePermission, usePermissions, usePrincipal, useRealtimeQuery, useRecentActivity, useResolve, useScope, useScopeReady, useSearch, useTheme, useTool, useTree, useType, useTypeHelpers, useTypes, useUnreadCounts, useUpdate, vfsKeys };
+export { type AccountInfo, type Channel, type ChannelCard, type ChannelMessage, type ChannelMessagesOptions, type ChannelMessagesPage, type ChannelMessagesResponse, type ChannelsOptions, type ComponentOpener, ComponentRenderer, type CreateParams, type DeleteParams, EnforcementDeniedError, type EnforcementPayload, type FieldDescriptor, type FileRef, type GatewayParams, type GatewayResponse, type InfiniteChannelMessagesOptions, type ItemVersionsOptions, type ItemVersionsResult, type ItemsFilter, KernelProvider, type LinkParams, type MoveParams, type Notification, type NotificationsOptions, type OpenEnvelope, type OpenOptions, type PrincipalData, type ResolveParams, type ResolveResponse, type ResolveResultItem, type SessionEntry, type TypeDefinition, type TypeHelpers, type TypeSchema, type UnreadCountsOptions, type UpdateParams, type UploadItem, type UploadOptions, type UploadResult, type UseFileUploadReturn, type VFSEdge, type VFSItem, auth, awaitScopeReady, callTool, clearCachedToken, clearSession, createItem, disconnectSSE, disposeVfsRealtimeWs, emitEvent, fetchChannelMessages, fetchChannelMessagesPage, fetchChannelMessagesWithCards, fetchEdgesForItem, fetchItemHistory, fetchItemVersions, fetchItems, fetchMemberFocus, fetchOpenEnvelope, fetchRecentActivity, fetchTypeDefinitions, fetchVfsChildren, fetchVfsChildrenPage, fetchVfsItem, fetchVfsItemById, fetchVfsTree, gatewayCall, getAccessToken, getAssetUrl, getDefaultSort, getRequiredFormFields, getScope, getScopeVersion, getSessionEntry, initSession, initVfsRealtimeWs, interpretSchema, invalidateAllVfs, invalidateChannelMessages, invalidateChildren, invalidateItem, invalidateOpenEnvelope, invalidatePathAndParent, invalidateSubtree, invalidateTypes, isScopeReady, listChildren, mount, mountRealtimeScope, normalizeItem, ping, pushChanges, queryClient, readItem, registerCleanup, resetAllSdkState, resolvePrincipalId, setCachedToken, setScope, setupRequireShim, signal, subscribeScope, subscribeToEvents, subscribeToPath, subscribeToScope, unmountRealtimeScope, updateItem, uploadFile, useAccounts, useAllChannels, useAsset, useAuth, useChannelMessages, useChannels, useChildren, useComponent, useCreate, useDelete, useDmChannels, useEdges, useEventStream, useFileUpload, useInfiniteChannelMessages, useInfiniteChildren, useInfiniteItems, useItem, useItemById, useItemHistory, useItemVersions, useItems, useLink, useList, useMemberFocus, useMove, useMutation, useNotifications, useOpen, usePermission, usePermissions, usePrincipal, useRealtimeQuery, useRecentActivity, useResolve, useScope, useScopeReady, useSearch, useTheme, useTool, useTree, useType, useTypeHelpers, useTypes, useUnreadCounts, useUpdate, vfsKeys };

package/dist/index.d.ts

@@ -664,6 +664,33 @@ interface ChannelMessage {
     intent_card?: Record<string, unknown>;
     thread_summary?: Array<Record<string, unknown>>;
 }
+/** A parsed card item bundled with channel messages from the kernel v2 response. */
+interface ChannelCard {
+    id: string;
+    path: string;
+    name: string;
+    createdAt: string;
+    action: string;
+    targetId?: string;
+    targetPath: string;
+    targetDisplayName: string;
+    targetDescription: string;
+    targetItemType: string;
+    /** Derived tool use ID (name without 'card-' prefix). */
+    toolId?: string;
+    /** Path of the parent message (for child cards). Undefined for sibling cards. */
+    parentMessagePath?: string;
+    visibility: string;
+}
+/** Full response from fetchChannelMessagesWithCards — includes bundled cards. */
+interface ChannelMessagesResponse {
+    messages: ChannelMessage[];
+    /** Cards that are direct children of messages in this page. Keyed by message path. */
+    messageCards: Map<string, ChannelCard[]>;
+    /** Cards that are direct siblings (children of the channel itself). */
+    siblingCards: ChannelCard[];
+    mode: 'top_level' | 'thread';
+}
 /**
  * Fetch channel messages via the kernel's `get-channel-messages` method.
  *
@@ -676,9 +703,24 @@ interface ChannelMessage {
  *                         If omitted, returns top-level messages.
  */
 declare function fetchChannelMessages(channelPath: string, parentMessageId?: string): Promise<ChannelMessage[]>;
+/**
+ * Fetch channel messages WITH bundled cards from the kernel v2 response.
+ *
+ * The kernel's get-channel-messages (v2) returns messages interleaved with
+ * their associated cards (both sibling cards and child cards). This function
+ * parses both and groups child cards by their parent message path.
+ *
+ * This eliminates the N+1 query problem where the frontend previously made
+ * separate `list` calls for each message to fetch its cards.
+ */
+declare function fetchChannelMessagesWithCards(channelPath: string, parentMessageId?: string): Promise<ChannelMessagesResponse>;
 /** Response shape from fetchChannelMessagesPage. */
 interface ChannelMessagesPage {
     messages: ChannelMessage[];
+    /** Cards grouped by parent message path (child cards of messages in this page). */
+    messageCards: Map<string, ChannelCard[]>;
+    /** Cards that are direct siblings of the channel (not nested under a message). */
+    siblingCards: ChannelCard[];
     /** Mode returned by kernel: 'top_level' or 'thread'. */
     mode: 'top_level' | 'thread';
 }
@@ -1482,14 +1524,24 @@ interface ChannelMessagesOptions {
     realtime?: boolean;
     enabled?: boolean;
 }
-/** Fetch channel messages via the kernel's `get-channel-messages` method. */
+/**
+ * Fetch channel messages via the kernel's `get-channel-messages` method.
+ *
+ * Now uses `fetchChannelMessagesWithCards` to get bundled cards in a single
+ * request, eliminating the N+1 query problem. Cards are returned alongside
+ * messages, grouped by parent message path.
+ */
 declare function useChannelMessages(options: ChannelMessagesOptions): {
     messages: ChannelMessage[];
+    /** Cards grouped by parent message path (child cards of messages). */
+    messageCards: Map<string, ChannelCard[]>;
+    /** Cards that are direct siblings of the channel (not nested under a message). */
+    siblingCards: ChannelCard[];
     threads: ChannelMessage[];
     isLoading: boolean;
     isFetching: boolean;
     error: Error | null;
-    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<ChannelMessage[], Error>>;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<ChannelMessagesResponse, Error>>;
 };
 /** Options for useInfiniteChannelMessages. */
 interface InfiniteChannelMessagesOptions {
@@ -1523,6 +1575,10 @@ interface InfiniteChannelMessagesOptions {
  */
 declare function useInfiniteChannelMessages(options: InfiniteChannelMessagesOptions): {
     messages: ChannelMessage[];
+    /** Cards grouped by parent message path (child cards of messages). */
+    messageCards: Map<string, ChannelCard[]>;
+    /** Cards that are direct siblings of the channel (not nested under a message). */
+    siblingCards: ChannelCard[];
     threads: ChannelMessage[];
     isLoading: boolean;
     isFetching: boolean;
@@ -1875,4 +1931,4 @@ declare function uploadFile(file: File | Blob, options: UploadOptions, onProgres
  */
 declare function useFileUpload(): UseFileUploadReturn;
 
-export { type AccountInfo, type Channel, type ChannelMessage, type ChannelMessagesOptions, type ChannelMessagesPage, type ChannelsOptions, type ComponentOpener, ComponentRenderer, type CreateParams, type DeleteParams, EnforcementDeniedError, type EnforcementPayload, type FieldDescriptor, type FileRef, type GatewayParams, type GatewayResponse, type InfiniteChannelMessagesOptions, type ItemVersionsOptions, type ItemVersionsResult, type ItemsFilter, KernelProvider, type LinkParams, type MoveParams, type Notification, type NotificationsOptions, type OpenEnvelope, type OpenOptions, type PrincipalData, type ResolveParams, type ResolveResponse, type ResolveResultItem, type SessionEntry, type TypeDefinition, type TypeHelpers, type TypeSchema, type UnreadCountsOptions, type UpdateParams, type UploadItem, type UploadOptions, type UploadResult, type UseFileUploadReturn, type VFSEdge, type VFSItem, auth, awaitScopeReady, callTool, clearCachedToken, clearSession, createItem, disconnectSSE, disposeVfsRealtimeWs, emitEvent, fetchChannelMessages, fetchChannelMessagesPage, fetchEdgesForItem, fetchItemHistory, fetchItemVersions, fetchItems, fetchMemberFocus, fetchOpenEnvelope, fetchRecentActivity, fetchTypeDefinitions, fetchVfsChildren, fetchVfsChildrenPage, fetchVfsItem, fetchVfsItemById, fetchVfsTree, gatewayCall, getAccessToken, getAssetUrl, getDefaultSort, getRequiredFormFields, getScope, getScopeVersion, getSessionEntry, initSession, initVfsRealtimeWs, interpretSchema, invalidateAllVfs, invalidateChannelMessages, invalidateChildren, invalidateItem, invalidateOpenEnvelope, invalidatePathAndParent, invalidateSubtree, invalidateTypes, isScopeReady, listChildren, mount, mountRealtimeScope, normalizeItem, ping, pushChanges, queryClient, readItem, registerCleanup, resetAllSdkState, resolvePrincipalId, setCachedToken, setScope, setupRequireShim, signal, subscribeScope, subscribeToEvents, subscribeToPath, subscribeToScope, unmountRealtimeScope, updateItem, uploadFile, useAccounts, useAllChannels, useAsset, useAuth, useChannelMessages, useChannels, useChildren, useComponent, useCreate, useDelete, useDmChannels, useEdges, useEventStream, useFileUpload, useInfiniteChannelMessages, useInfiniteChildren, useInfiniteItems, useItem, useItemById, useItemHistory, useItemVersions, useItems, useLink, useList, useMemberFocus, useMove, useMutation, useNotifications, useOpen, usePermission, usePermissions, usePrincipal, useRealtimeQuery, useRecentActivity, useResolve, useScope, useScopeReady, useSearch, useTheme, useTool, useTree, useType, useTypeHelpers, useTypes, useUnreadCounts, useUpdate, vfsKeys };
+export { type AccountInfo, type Channel, type ChannelCard, type ChannelMessage, type ChannelMessagesOptions, type ChannelMessagesPage, type ChannelMessagesResponse, type ChannelsOptions, type ComponentOpener, ComponentRenderer, type CreateParams, type DeleteParams, EnforcementDeniedError, type EnforcementPayload, type FieldDescriptor, type FileRef, type GatewayParams, type GatewayResponse, type InfiniteChannelMessagesOptions, type ItemVersionsOptions, type ItemVersionsResult, type ItemsFilter, KernelProvider, type LinkParams, type MoveParams, type Notification, type NotificationsOptions, type OpenEnvelope, type OpenOptions, type PrincipalData, type ResolveParams, type ResolveResponse, type ResolveResultItem, type SessionEntry, type TypeDefinition, type TypeHelpers, type TypeSchema, type UnreadCountsOptions, type UpdateParams, type UploadItem, type UploadOptions, type UploadResult, type UseFileUploadReturn, type VFSEdge, type VFSItem, auth, awaitScopeReady, callTool, clearCachedToken, clearSession, createItem, disconnectSSE, disposeVfsRealtimeWs, emitEvent, fetchChannelMessages, fetchChannelMessagesPage, fetchChannelMessagesWithCards, fetchEdgesForItem, fetchItemHistory, fetchItemVersions, fetchItems, fetchMemberFocus, fetchOpenEnvelope, fetchRecentActivity, fetchTypeDefinitions, fetchVfsChildren, fetchVfsChildrenPage, fetchVfsItem, fetchVfsItemById, fetchVfsTree, gatewayCall, getAccessToken, getAssetUrl, getDefaultSort, getRequiredFormFields, getScope, getScopeVersion, getSessionEntry, initSession, initVfsRealtimeWs, interpretSchema, invalidateAllVfs, invalidateChannelMessages, invalidateChildren, invalidateItem, invalidateOpenEnvelope, invalidatePathAndParent, invalidateSubtree, invalidateTypes, isScopeReady, listChildren, mount, mountRealtimeScope, normalizeItem, ping, pushChanges, queryClient, readItem, registerCleanup, resetAllSdkState, resolvePrincipalId, setCachedToken, setScope, setupRequireShim, signal, subscribeScope, subscribeToEvents, subscribeToPath, subscribeToScope, unmountRealtimeScope, updateItem, uploadFile, useAccounts, useAllChannels, useAsset, useAuth, useChannelMessages, useChannels, useChildren, useComponent, useCreate, useDelete, useDmChannels, useEdges, useEventStream, useFileUpload, useInfiniteChannelMessages, useInfiniteChildren, useInfiniteItems, useItem, useItemById, useItemHistory, useItemVersions, useItems, useLink, useList, useMemberFocus, useMove, useMutation, useNotifications, useOpen, usePermission, usePermissions, usePrincipal, useRealtimeQuery, useRecentActivity, useResolve, useScope, useScopeReady, useSearch, useTheme, useTool, useTree, useType, useTypeHelpers, useTypes, useUnreadCounts, useUpdate, vfsKeys };

package/dist/index.js

@@ -30,6 +30,7 @@ __export(src_exports, {
   emitEvent: () => emitEvent,
   fetchChannelMessages: () => fetchChannelMessages,
   fetchChannelMessagesPage: () => fetchChannelMessagesPage,
+  fetchChannelMessagesWithCards: () => fetchChannelMessagesWithCards,
   fetchEdgesForItem: () => fetchEdgesForItem,
   fetchItemHistory: () => fetchItemHistory,
   fetchItemVersions: () => fetchItemVersions,
@@ -765,6 +766,26 @@ async function fetchItems(filter) {
     return { items: [], total_hint: 0 };
   }
 }
+function parseChannelCards(rawItems) {
+  return rawItems.filter((i) => i.item_type === "card").map((i) => {
+    const td = i.type_data || {};
+    return {
+      id: i.id || "",
+      path: i.path || "",
+      name: i.name || (i.path || "").split("/").pop() || "",
+      createdAt: i.created_at || "",
+      action: td.action || "created",
+      targetId: td.target_id || void 0,
+      targetPath: td.target_path || "",
+      targetDisplayName: td.target_display_name || "",
+      targetDescription: td.target_description || "",
+      targetItemType: td.target_item_type || "",
+      toolId: (i.name || "").startsWith("card-") ? (i.name || "").substring(5) : void 0,
+      parentMessagePath: i.parent_message_path || void 0,
+      visibility: td.visibility || "private"
+    };
+  }).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
 function parseChannelMessages(rawItems) {
   return rawItems.filter((i) => i.item_type === "message").map((i) => {
     const td = i.type_data || {};
@@ -803,6 +824,40 @@ async function fetchChannelMessages(channelPath, parentMessageId) {
     return [];
   }
 }
+async function fetchChannelMessagesWithCards(channelPath, parentMessageId) {
+  try {
+    const params = { channel_path: channelPath };
+    if (parentMessageId) params.parent_message_id = parentMessageId;
+    const response = await gatewayCall("get-channel-messages", params);
+    const raw = response;
+    const items = raw.messages || [];
+    const messages = parseChannelMessages(items);
+    const cards = parseChannelCards(items);
+    const messageCards = /* @__PURE__ */ new Map();
+    const siblingCards = [];
+    for (const card of cards) {
+      if (card.parentMessagePath) {
+        const existing = messageCards.get(card.parentMessagePath) || [];
+        existing.push(card);
+        messageCards.set(card.parentMessagePath, existing);
+      } else {
+        siblingCards.push(card);
+      }
+    }
+    return {
+      messages,
+      messageCards,
+      siblingCards,
+      mode: raw.mode || "top_level"
+    };
+  } catch (err) {
+    console.error(
+      `[gateway] Failed to fetch channel messages with cards for ${channelPath}:`,
+      err
+    );
+    return { messages: [], messageCards: /* @__PURE__ */ new Map(), siblingCards: [], mode: "top_level" };
+  }
+}
 async function fetchChannelMessagesPage(channelPath, options) {
   try {
     const params = { channel_path: channelPath };
@@ -813,8 +868,22 @@ async function fetchChannelMessagesPage(channelPath, options) {
     const response = await gatewayCall("get-channel-messages", params);
     const raw = response;
     const items = raw.messages || [];
+    const cards = parseChannelCards(items);
+    const messageCards = /* @__PURE__ */ new Map();
+    const siblingCards = [];
+    for (const card of cards) {
+      if (card.parentMessagePath) {
+        const existing = messageCards.get(card.parentMessagePath) || [];
+        existing.push(card);
+        messageCards.set(card.parentMessagePath, existing);
+      } else {
+        siblingCards.push(card);
+      }
+    }
     return {
       messages: parseChannelMessages(items),
+      messageCards,
+      siblingCards,
       mode: raw.mode || "top_level"
     };
   } catch (err) {
@@ -822,7 +891,7 @@ async function fetchChannelMessagesPage(channelPath, options) {
       `[gateway] Failed to fetch channel messages page for ${channelPath}:`,
       err
     );
-    return { messages: [], mode: "top_level" };
+    return { messages: [], messageCards: /* @__PURE__ */ new Map(), siblingCards: [], mode: "top_level" };
   }
 }
 function invalidateChildren(path) {
@@ -2262,7 +2331,7 @@ function useChannelMessages(options) {
   const debounceRef = useRef(null);
   const query = useQuery({
     queryKey: stableKey,
-    queryFn: () => fetchChannelMessages(channelPath, parentMessageId),
+    queryFn: () => fetchChannelMessagesWithCards(channelPath, parentMessageId),
     enabled: isEnabled
   });
   useEffect(() => {
@@ -2276,7 +2345,7 @@ function useChannelMessages(options) {
         }, 500);
       },
       (data) => {
-        return data.item_type === "message" && typeof data.path === "string" && data.path.startsWith(channelPath);
+        return (data.item_type === "message" || data.item_type === "card") && typeof data.path === "string" && data.path.startsWith(channelPath);
       }
     );
     return () => {
@@ -2284,9 +2353,16 @@ function useChannelMessages(options) {
       if (debounceRef.current) clearTimeout(debounceRef.current);
     };
   }, [realtime, isEnabled, channelPath, stableKey, qc]);
-  const messages = query.data ?? [];
+  const response = query.data;
+  const messages = response?.messages ?? [];
+  const messageCards = response?.messageCards ?? /* @__PURE__ */ new Map();
+  const siblingCards = response?.siblingCards ?? [];
   return {
     messages,
+    /** Cards grouped by parent message path (child cards of messages). */
+    messageCards,
+    /** Cards that are direct siblings of the channel (not nested under a message). */
+    siblingCards,
     threads: useMemo(() => messages.filter((m) => m.reply_count > 0), [messages]),
     isLoading: query.isLoading,
     isFetching: query.isFetching,
@@ -2338,17 +2414,60 @@ function useInfiniteChannelMessages(options) {
     }
     return flat.sort((a, b) => a.seq - b.seq);
   }, [query.data?.pages]);
+  const { messageCards, siblingCards } = useMemo(() => {
+    const mc = /* @__PURE__ */ new Map();
+    const sc = [];
+    if (!query.data?.pages) return { messageCards: mc, siblingCards: sc };
+    const seenCards = /* @__PURE__ */ new Set();
+    for (const page of query.data.pages) {
+      for (const [path, cards] of page.messageCards) {
+        for (const card of cards) {
+          if (seenCards.has(card.id)) continue;
+          seenCards.add(card.id);
+          const existing = mc.get(path) || [];
+          existing.push(card);
+          mc.set(path, existing);
+        }
+      }
+      for (const card of page.siblingCards) {
+        if (seenCards.has(card.id)) continue;
+        seenCards.add(card.id);
+        sc.push(card);
+      }
+    }
+    return { messageCards: mc, siblingCards: sc };
+  }, [query.data?.pages]);
+  const qc = useQueryClient();
+  const debounceRef = useRef(null);
+  const stableKey = useMemo(
+    () => [...vfsKeys.channelMessages(channelPath || "", parentMessageId), "infinite", limit],
+    [channelPath, parentMessageId, limit]
+  );
   useEffect(() => {
     if (!realtime || !channelPath || !queryEnabled) return;
-    const unsub = subscribeToEvents(channelPath, (event) => {
-      if (event.event_type === "vfs_change") {
-        query.refetch();
+    const unsub = subscribeToEvents(
+      "vfs_change",
+      () => {
+        if (debounceRef.current) clearTimeout(debounceRef.current);
+        debounceRef.current = setTimeout(() => {
+          qc.invalidateQueries({ queryKey: stableKey });
+        }, 500);
+      },
+      (data) => {
+        return (data.item_type === "message" || data.item_type === "card") && typeof data.path === "string" && data.path.startsWith(channelPath);
       }
-    });
-    return unsub;
-  }, [realtime, channelPath, queryEnabled]);
+    );
+    return () => {
+      unsub();
+      if (debounceRef.current) clearTimeout(debounceRef.current);
+    };
+  }, [realtime, channelPath, queryEnabled, stableKey, qc]);
   return {
     messages,
+    /** Cards grouped by parent message path (child cards of messages). */
+    messageCards,
+    /** Cards that are direct siblings of the channel (not nested under a message). */
+    siblingCards,
     threads: messages.filter((m) => m.reply_count > 0),
     isLoading: query.isLoading,
     isFetching: query.isFetching,
@@ -3115,6 +3234,6 @@ function useFileUpload() {
 // src/index.ts
 __registerSdkExports(src_exports);
 
-export { ComponentRenderer, EnforcementDeniedError, KernelProvider, auth, awaitScopeReady, callTool, clearCachedToken, clearSession, createItem, disconnectSSE, disposeVfsRealtimeWs, emitEvent, fetchChannelMessages, fetchChannelMessagesPage, fetchEdgesForItem, fetchItemHistory, fetchItemVersions, fetchItems, fetchMemberFocus, fetchOpenEnvelope, fetchRecentActivity, fetchTypeDefinitions, fetchVfsChildren, fetchVfsChildrenPage, fetchVfsItem, fetchVfsItemById, fetchVfsTree, gatewayCall, getAccessToken, getAssetUrl, getDefaultSort, getRequiredFormFields, getScope, getScopeVersion, getSessionEntry, initSession, initVfsRealtimeWs, interpretSchema, invalidateAllVfs, invalidateChannelMessages, invalidateChildren, invalidateItem, invalidateOpenEnvelope, invalidatePathAndParent, invalidateSubtree, invalidateTypes, isScopeReady, listChildren, mount, mountRealtimeScope, normalizeItem, ping, pushChanges, queryClient, readItem, registerCleanup, resetAllSdkState, resolvePrincipalId, setCachedToken, setScope, setupRequireShim, signal, subscribeScope, subscribeToEvents, subscribeToPath, subscribeToScope, unmountRealtimeScope, updateItem, uploadFile, useAccounts, useAllChannels, useAsset, useAuth, useChannelMessages, useChannels, useChildren, useComponent, useCreate, useDelete, useDmChannels, useEdges, useEventStream, useFileUpload, useInfiniteChannelMessages, useInfiniteChildren, useInfiniteItems, useItem, useItemById, useItemHistory, useItemVersions, useItems, useLink, useList, useMemberFocus, useMove, useMutation, useNotifications, useOpen, usePermission, usePermissions, usePrincipal, useRealtimeQuery, useRecentActivity, useResolve, useScope, useScopeReady, useSearch, useTheme, useTool, useTree, useType, useTypeHelpers, useTypes, useUnreadCounts, useUpdate, vfsKeys };
+export { ComponentRenderer, EnforcementDeniedError, KernelProvider, auth, awaitScopeReady, callTool, clearCachedToken, clearSession, createItem, disconnectSSE, disposeVfsRealtimeWs, emitEvent, fetchChannelMessages, fetchChannelMessagesPage, fetchChannelMessagesWithCards, fetchEdgesForItem, fetchItemHistory, fetchItemVersions, fetchItems, fetchMemberFocus, fetchOpenEnvelope, fetchRecentActivity, fetchTypeDefinitions, fetchVfsChildren, fetchVfsChildrenPage, fetchVfsItem, fetchVfsItemById, fetchVfsTree, gatewayCall, getAccessToken, getAssetUrl, getDefaultSort, getRequiredFormFields, getScope, getScopeVersion, getSessionEntry, initSession, initVfsRealtimeWs, interpretSchema, invalidateAllVfs, invalidateChannelMessages, invalidateChildren, invalidateItem, invalidateOpenEnvelope, invalidatePathAndParent, invalidateSubtree, invalidateTypes, isScopeReady, listChildren, mount, mountRealtimeScope, normalizeItem, ping, pushChanges, queryClient, readItem, registerCleanup, resetAllSdkState, resolvePrincipalId, setCachedToken, setScope, setupRequireShim, signal, subscribeScope, subscribeToEvents, subscribeToPath, subscribeToScope, unmountRealtimeScope, updateItem, uploadFile, useAccounts, useAllChannels, useAsset, useAuth, useChannelMessages, useChannels, useChildren, useComponent, useCreate, useDelete, useDmChannels, useEdges, useEventStream, useFileUpload, useInfiniteChannelMessages, useInfiniteChildren, useInfiniteItems, useItem, useItemById, useItemHistory, useItemVersions, useItems, useLink, useList, useMemberFocus, useMove, useMutation, useNotifications, useOpen, usePermission, usePermissions, usePrincipal, useRealtimeQuery, useRecentActivity, useResolve, useScope, useScopeReady, useSearch, useTheme, useTool, useTree, useType, useTypeHelpers, useTypes, useUnreadCounts, useUpdate, vfsKeys };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map